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

mtaDequeueMessageFinish()

Complete a message dequeue or defer a message for later processing.

Syntax


int mtaDequeueMessageFinish(mta_dq_t *dq_ctx,
                            int       item_code, ...);

Arguments

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.

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.

Return Values

Return Values  

Description  

Normal, successful completion. 

MTA_BADARGS

Received for one of two reasons: 

  1. A NULL value was supplied for the dq_ctx call argument, an invalid dequeue context was supplied for dq_ctx.

  2. A required argument to an item code was NULL.

MTA_NO

Unable to dequeue the message. This error can result from an attempt to enqueue a new message to a subset of recipients. 

MTA_NOSUCHITEM

An invalid item code was specified. 

MTA_ORDER

Call made out of sequence. The call was made either before the recipient list has been exhausted with mtaDequeueRecipientNext(), or after the message had been dequeued or deferred with mtaDequeueMessageFinish().

MTA_THREAD

The MTA SDK detected simultaneous use of the dequeue context by two different threads. 

Example

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