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

Description

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:

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:

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: 

  1. The address of the string containing the reason text.

  2. The length in bytes of the reason text. If a value of zero is passed for the length, then the reason text must be NULL terminated.