mtaAddressGetN()

Extract an address from a list of parsed addresses.

Syntax

int mtaAddressGetN(mta_adr_t   *adr_ctx,
                   size_t       address_index,
                   const char **address,
                   size_t      *address_len,
                   int          elements);

Arguments

Description

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.

Elements Argument

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

Address Argument

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);

Return Values

Example

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);
}