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