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


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





An address context created by a previous call to mtaAddressParse().


Index of the address to retrieve. It is an index into a list of addresses. The first address has an index of 0. 


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. 


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. 


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.

Elements Argument

Using the nomenclature of RFC 822, an address has the following four-element format:

phrase <@route:local-part@domain>

Note –

The @route: element is referred to as a source route and is rarely seen.

An example address with all four elements is:

Judy Smith <>

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:

For example, to select just the local and domain parts, use the following value for the elements argument:


When a value of zero is supplied for elements the following default bitmask is assumed:


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,
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

Return Value  



Normal, successful completion 


One of the following conditions occurred: 

  1. A NULL value for the adr_content argument

  2. An invalid address context

  3. An invalid bitmask for elements


The value supplied for the address_index is equal to or greater than the number of addresses in the address list.


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 <\>,",
        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);