Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference

`mtaAddressParse()`

Parse a list of comma separated RFC 822 addresses.

Syntax

int mtaAddressParse(mta_adr_t **adr_ctx,
                    size_t     *address_count,
                    const char *address_list,
                    size_t      address_list_len,
                    int         item_code, ...);

Arguments

Argument	Description
`adr_ctx`	The address context created for the parsed list of addresses.
`address_count`	The number of addresses parsed.
`address_list`	A character string containing the list of comma separated RFC 822 addresses to be parsed. The string must be NULL terminated if a value of zero is passed for `address_list_len`.
`address_list_len`	The length in bytes of the string of addresses to parse, not including any NULL terminator. If a value of zero is passed for this argument, then the length of `address_list` will automatically be determined.
`item_code`	An optional list of item codes. The list must be terminated with an integer argument with value `0`.

Description

This routine parses a list of one or more comma separated RFC 822 addresses. The input list can be of any arbitrary length. The result of the parse is represented by an address context and a count of the parsed addresses. Each parsed address can then be individually extracted from the parsed list with a call to mtaAddresGetN(). The address context should be disposed of with a call to mtaAddressFinish(). When there are no valid addresses in the input line, the returned context will be NULL and the count zero.

Note –

There are two item codes that can be used in the item_code argument. A NULL value can be passed for either or both of the adr_ctx and address_count arguments. When NULL is passed for both, all that is learned by calling the routine is whether or not the address list is syntactically valid.

The following table lists the item codes for this routine, their additional required arguments, and gives a description of each.

Item Codes	Additional Arguments	Description
`MTA_DOMAIN`	`const char *domain` `size_t domain_len`	Specify a domain name to append to short-form addresses, such as `sue`, in order to create a fully qualified address, for example, `sue@siroe.com`. It must be followed by two additional call arguments: the domain name to use and the length in bytes of that domain name. If a value of `0` is passed for the length, then the domain name must be NULL terminated.
`MTA_ITEM_LIST`	`mta_item_list_t *item_lis`t	Specify a pointer to an item list array. The array must be terminated with a final array entry with an item code value of `0`. For further information on item lists, see Item Codes and Item Lists.

Item Codes

Additional Arguments

Description

MTA_DOMAIN

const char *domain

size_t domain_len

Specify a domain name to append to short-form addresses, such as sue, in order to create a fully qualified address, for example, sue@siroe.com.

It must be followed by two additional call arguments: the domain name to use and the length in bytes of that domain name. If a value of 0 is passed for the length, then the domain name must be NULL terminated.

MTA_ITEM_LIST

mta_item_list_t *item_list

Specify a pointer to an item list array. The array must be terminated with a final array entry with an item code value of 0. For further information on item lists, see Item Codes and Item Lists.

Return Values

Return Value	Description
`0`	Normal, successful completion.
`MTA_BADARGS`	A NULL value was supplied for the `address_list` argument or an optional item code argument.
`MTA_NO`	Unable to parse the address list. The likely cause is that one or more addresses in the list is syntactically invalid.
`MTA_NOMEM`	Insufficient virtual memory.
`MTA_NOSUCHITEM`	An invalid item code was supplied.
`MTA_STRTRUERR`	Item code string argument is too long.

Example

See the code example for mtaAddressGetN() for a sample code fragment that uses mtaAddressParse().