Extract an address from a list of parsed addresses.
int mtaAddressGetN(mta_adr_t *adr_ctx, size_t address_index, const char **address, size_t *address_len, int elements); |
Arguments |
Description |
---|---|
adr_ctx |
An address context created by a previous call to mtaAddressParse(). |
address_index |
Index of the address to retrieve. It is an index into a list of addresses. The first address has an index of 0. |
address |
Pointer to receive the selected address (a pointer to a buffer within the address context). The address will be NULL terminated. A NULL may be passed for this call argument if you do not wish to receive the pointer. |
address_len |
The length in bytes of the selected address, not including any NULL terminator. NULL may be passed for this call argument if you do not wish to receive the length. |
elements |
A bitmask indicating which RFC 822 mailbox elements of the address to return, such as phrase, route, local-part, or domain. Any combination of these elements may be returned. |
This routine retrieves the Nth address from a list of parsed addresses. The list of addresses must first be parsed with mtaAddressParse().
Either the entire address or just a portion of it may be retrieved.
Using the nomenclature of RFC 822, an address has the following four-element format:
phrase <@route:local-part@domain>
The @route: element is referred to as a source route and is rarely seen.
An example address with all four elements is:
Judy Smith <@siroe.com:judy.smith@email.siroe.com>
The elements argument is a bitmask indicating which of these elements to return. The bitmask is formed by a logical OR of the following symbolic constants defined in the mtasdk.h header file:
MTA_ADDR_PHRASE– In the example, the phrase part is Judy Smith.
MTA_ADDR_ROUTE– In the example, the route part is @siroe.com.
MTA_ADDR_LOCAL– In the example, the local part is judy.smith.
MTA_ADDR_DOMAIN– In the example, the domain part is email.siroe.com.
For example, to select just the local and domain parts, use the following value for the elements argument:
MTA_ADDR_LOCAL | MTA_ADDR_DOMAIN
When a value of zero is supplied for elements the following default bitmask is assumed:
MTA_ADDR_ROUTE | MTA_ADDR_LOCAL | MTA_ADDR_DOMAIN
This routine returns a pointer to the retrieved address and not the address itself. This pointer is to a buffer within the address context. Each time the routine is called with the same address context, that buffer is overwritten. Therefore, care must be taken when specifying the address argument. The following code example correctly specifies how the argument should be used when multiple calls are involved:
mtaAddressGetN(adr_ctx, 0, &ptr, NULL, MTA_ADDR_LOCAL); strcpy(buf, ptr); strcat(buf, "@"); mtaAddressGetN(adr_ctx, 0, &ptr, NULL, MTA_ADDR_DOMAIN); strcat(buf, ptr); |
Alternately, it could also be coded as shown in the following code fragment:
mtaAddressGetN(adr_ctx, 0, &ptr, NULL, MTA_ADDR_LOCAL | MTA_ADDR_DOMAIN); strcpy(buf, ptr); |
However, since the pointer points to the same buffer for each call, and is overwritten at each call, it would be incorrect to code it as shown in the following code example:
mtaAddressGetN(adr_ctx, 0, &local, NULL, MTA_ADDR_LOCAL); mtaAddressGetN(adr_ctx, 0, &domain, NULL, MTA_ADDR_DOMAIN); strcpy(buf, local); strcat(buf, "@"); strcat(buf, domain); |
The following is a code fragment that parses and displays the individual addresses from a list of two addresses, using mtaAddressGetN():
ires = mtaAddressParse(&adr_ctx, &adr_count, "Judy Public <judy.public@siroe.com\>, sue@siroe.com", 0, 0); for (i = 0; i < adr_count; i++) { mtaAddressGetN(adr_ctx, i, &ptr, NULL, MTA_ADDR_LOCAL | MTA_ADDR_DOMAIN); printf("Address %d: %s\n", i, ptr); } |