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

mtaDequeueRecipientNext()

Obtain the next envelope recipient address for the queued message file.

Syntax


int mtaDequeueRecipientNext(mta_dq_t    *dq_ctx,
                            const char **env_to,
                            size_t      *env_to_len,
                            int          item code, ...);

Arguments

Argument  

Description  

dq_ctx

A dequeue context created by mtaDequeueStart().

env_to

Optional address of a pointer to receive the memory address of the next envelope recipient address. The recipient address will not be NULL terminated. 

env_to_len

Optional address of a size_t to receive the length of the returned recipient address. A value of NULL may be passed for this argument.

item_code

An optional list of item codes. See the description section that follows for a list of item codes. The list must be terminated with an integer argument with value 0.

Description

The first step in processing a queued message is to retrieve its list of envelope recipient addresses. This is done by repeatedly calling mtaDequeueRecipientNext() until a status code of MTA_EOF is returned. Note that each call that returns a recipient address will return a status code of 0 (MTA_OK). The final call, which returns MTA_EOF, will not return a recipient address.

The processing of the list of envelope recipient addresses will, in general, be unique to each channel. Intermediate processing channels should simply re-enqueue a new message and copy the envelope recipient list verbatim over to the new message being enqueued, being sure to specify the MTA_ENV_TO and MTA_DQ_CONTEXT item codes to mtaEnqueueTo(). The envelope recipient list must be read in its entirety before attempting to read the message itself with mtaDequeueLineNext(). Failure to do so will result in an MTA_ORDER error being returned by mtaDequeueLineNext().

This routine accepts the same item codes as mtaDequeueInfo(). The code fragments are equivalent also, (compare the examples). Consequently, the mtaDequeueInfo() routine might appear superfluous. However, it also serves as a means of obtaining, in a single, non-repeated call, information about the overall message itself, such as the message’s envelope ID.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_BADARGS

This value was returned for one of the following reasons: 

  1. A NULL value was supplied for the dq_ctx call argument.

  2. An invalid dequeue context was supplied for dq_ctx.

  3. A NULL value was supplied for a required item code argument.

MTA_NOMEM

Insufficient virtual memory. 

MTA_EOF

The recipient list has been completely read; there are no further recipient addresses to return. 

MTA_THREAD

Concurrent use of the dequeue context by two different threads has been detected. 

Example

This code fragment illustrates an intermediate processing channel using this routine to fetch recipient addresses.


int dflags, istat;
const char *to, *ito;
while (!(istat = mtaDequeueRecipientNext(dq, &to, NULL,
                                MTA_DELIVERY_FLAGS, &dflags,
                                MTA_IRCPT_TO, &ito, NULL, 0)))
    printf("Delivery flags: %d\n"
           "Intermediate recipient address: %s\n", dflags, ito);
if (istat != MTA_EOF)
    printf("An error occured; %s\n", mtaStrError(istat));