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


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


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





A dequeue context created by mtaDequeueStart().


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


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.


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.


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  



Normal, successful completion. 


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.


Insufficient virtual memory. 


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


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


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