Complete a message dequeue or defer a message for later processing.
int mtaDequeueMessageFinish(mta_dq_t *dq_ctx, int item_code, ...); |
Arguments |
Description |
---|---|
dq_ctx |
A dequeue context created by mtaDequeueStart(). |
item_code |
An optional list of item codes. See the description section the follows for a list of item codes. The list must be terminated with an integer argument with value 0. |
Before completing processing of a queued message, the disposition of each envelope recipient must be set either by repeated calls to mtaDequeueRecipientDisposition(), or by means of the MTA_DISP item code for mtaDequeueMessageFinish(). For the former, a call should be made for each envelope recipient address. For the latter, the disposition set with MTA_DISP applies to all envelope recipients, overriding any previous settings made with mtaDequeueRecipientDisposition(). It is important that the dispositions be set correctly because they influence whether or not the message is deleted from the channel’s queue by mtaDequeueMessageFinish(). Incorrectly setting the dispositions can lead to duplicate message delivery, or, worse yet, lost mail.
To complete processing of a queued message, call mtaDequeueMessageFinish(). Upon being called, the routine performs one of three possible actions:
If all recipients have a disposition indicating successful processing or a permanent failure, then the underlying message file is deleted from the channel’s queue and any necessary notification messages are sent. This corresponds to the dispositions: MTA_DISP_DELIVERED, MTA_DISP_FAILED, MTA_DISP_RELAYED, MTA_DISP_RELAYED_FOREIGN, MTA_DISP_RETURN, and MTA_DISP_TIMEDOUT.
If all recipients have a disposition indicating a temporary processing problem or if the MTA_ABORT item code is specified, then the message file is left in the channel’s queue and a subsequent processing attempt is scheduled. The MTA_DISP_DEFERRED disposition is the only disposition that indicates a temporary processing problem. Generation of delay notifications is handled by a special MTA process referred to as the return job. Generation of delay notifications is not handled by mtaDequeueMessageFinish().
If only a subset of the recipients have a disposition indicating a temporary processing problem, then a new message is placed in the channel’s queue. This new message is identical to the current message being processed except that its envelope recipient list contains just those recipients whose disposition indicates a temporary processing problem. The current message being processed is then removed from the channel’s queue and any necessary notifications are sent for the recipients that had dispositions indicating successful processing or a permanent failure.
After mtaDequeueMessageFinish() is called, the dequeue context passed to it is no longer valid, regardless of the status it returns. When it returns an error status, it also defers the message and all of its recipients for later processing. This is done regardless of the disposition of the recipients. Doing otherwise could potentially lead to lost mail.
Internet standards require that notifications concerning a message be directed to the message’s envelope From: address. In addition, the following two rules apply:
Automatically generated notification messages themselves must have an empty envelope From: address.
Notifications must not be sent for messages with an empty envelope From: address.
These two rules combine to prevent certain broad classes of message loops. The MTA SDK strictly adheres to these Internet requirements.
Whenever a temporary processing error occurs and the channel can no longer process a queued message, processing of the message should be deferred until a later time. Processing for all recipients is deferred regardless of any prior disposition settings. Temporary processing errors include such errors as: insufficient virtual memory, network problems, disk errors, and other unexpected processing errors.
The following table lists the item codes for this routine, the additional arguments they take, and gives a description of each one.
Item Codes |
Additional Arguments |
Description |
---|---|---|
MTA_ABORT |
None |
When this item code is specified, processing of the message is deferred for all recipients of the message. The message is left in the channel’s queue and a later processing attempt is scheduled. |
MTA_DISP |
size_t disposition |
Use the MTA_DISP item code to set the disposition for all recipients of the message. This disposition will override any prior disposition settings. This item code must be followed by one additional call argument: the disposition value to set. See the description of mtaDequeueRecipientDisposition() for a discussion of the disposition settings. |
MTA_ITEM_LIST |
mta_item_list_t *item_list |
Specify a pointer to an item list array. The item list array must be terminated with a final array entry with an item code value of zero. For further information on item list usage, see Item Codes and Item Lists. |
MTA_REASON |
const char *reason size_t reason_len |
When deferring processing of a message, the reason for the deferral may be saved as part of the messages delivery history. This delivery history may be viewed by system managers with the MTA qm utility. It may also be reported in delay notifications. This item code must be followed by two additional call arguments:
|
There are three code examples, each showing variations on deferring a message.
The following code fragment shows how to use this routine to defer processing of a message until a later time by calling the routine with the MTA_ABORT item code:
mtaDequeueMessageFinish(dq_ctx, MTA_ABORT, 0);
The following code fragment shows how to use this routine to defer processing of a message and setting the disposition:
mtaDequeueMessageFinish(dq_ctx, MTA_DISP, MTA_DISP_DEFERRED, 0);
The following code fragment shows how to use this routine to defer processing of a message with a text string explaining the reason for the deferral:
mtaDequeueMessageFinish(dq_ctx, MTA_ABORT, MTA_REASON, "Temporary network error", 0, 0); |