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

`mtaDequeueRecipientDisposition()`

Specify the delivery status (disposition) of an envelope recipient address.

Syntax

int mtaDequeueRecipientDisposition(mta_dq_t   *dq_ctx,
                                   const char *env_to,
                                   size_t      env_to_len,
                                   size_t      disposition,
                                   int         item_code, ...);

Arguments

Arguments	Description
`dq_ctx`	A dequeue context created by `mtaDequeueStart()`.
`env_to`	The recipient address to effect the setting for. This must be the recipient’s envelope `To:` address as returned by `mtaDequeueRecipientNext()` and not some transformation of that address. If a value of zero is passed for the `env_to_len` argument, then this string must be NULL terminated.
`env_to_len`	The length in bytes of the recipient address, `env_to`. This length does not include any NULL terminator. If a value of zero is passed for this argument, then the recipient address string must be NULL terminated.
`disposition`	The delivery status disposition to set for this recipient address. See the description section that follows for further details.
`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`.

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(). The delivery status dispositions, and their descriptions are listed in the table that follows. Pass one of these values for the disposition argument.

Delivery Status Dispositions	Description
`MTA_DISP_DEFERRED`	Processing for this recipient has experienced a temporary failure (for example, the network is temporarily down, the disk is currently full, the recipient is presently over quota). Schedule a later processing attempt for this recipient.
`MTA_DISP_DELIVERED`	Final delivery has been effected for this recipient address. Any required delivery notifications should be generated. Intermediate processing channels should use `MTA_DISP_RELAYED` rather than `MTA_DISP_DELIVERED`. Use of `MTA_DISP_DELIVERED` by an intermediate processing channel might incorrectly generate a delivery status notification when final delivery has not yet been effected.
`MTA_DISP_FAILED`	Processing for this recipient has experienced a permanent failure. The message is and will remain undeliverable for this recipient. No further delivery attempts are to be made for this recipient. Any required non-delivery notifications should be generated.
`MTA_DISP_RELAYED`	The message has been successfully processed for this recipient. No further processing by this channel is needed for this recipient address. No delivery status notification is generated as final delivery will be effected by another entity capable of generating any needed notification messages. This disposition should be used by intermediate processing channels. It should also be used by gateways that transfer the message to other mail systems capable of generating the necessary notification messages.
`MTA_DISP_RELAYED_FOREIGN`	The message has been successfully processed for this recipient. No further processing by this channel is needed for this recipient address; however, a relayed delivery status notification should be generated if delivery notification was requested for this recipient. This disposition should be used by gateways that transfer the message to other mail systems incapable of generating the necessary notification messages.
`MTA_DISP_RETURN`	Generate a postmaster non-delivery notification for this recipient and, for this recipient, remove the message from the channel’s queue. This disposition is not intended for use by channels. Instead, it should be used by postmaster utilities that allow the postmaster to manually return mail messages.
`MTA_DISP_TIMEDOUT`	Generate a timed-out non-delivery notification indicating that the message has been undeliverable for too long and no further delivery attempts will be made. This disposition is not intended for use by channels. Instead, it is meant for use by the MTA return job that scans the MTA queues, returning old, undeliverable messages to their originators.

This table lists the item codes for this routine, and the additional required arguments, and gives a description of each.

Item Codes	Additional Arguments	Description
`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`	The reason for ascribing the disposition to this recipient address. This reason might then appear in any delivery or non-delivery status notification for that recipient. This item code must be followed by two additional call arguments: the address of the string containing the reason text. 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.

Item Codes

Additional Arguments

Description

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

The reason for ascribing the disposition to this recipient address. This reason might then appear in any delivery or non-delivery status notification for that recipient.

This item code must be followed by two additional call arguments:

the address of the string containing the reason text.
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
`0`	Normal, successful completion.
`MTA_BADARGS`	This value was returned for one of the following reasons: A NULL value was supplied for the `dq_ctx` call argument. An invalid dequeue context was supplied for `dq_ctx`. A required argument to an item code was NULL.
`MTA_NOSUCHITEM`	An invalid item code was specified.
`MTA_THREAD`	The MTA SDK detected simultaneous use of the dequeue context by two different threads.

Example

This code fragment assumes a condition in which the recipient address is invalid. It returns a disposition of MTA_DISP_FAILED with an explanation.

mtaDequeueRecipientDisposition(
   dq_ctx, "sue@siroe.com", 0, MTA_DISP_FAILED,
   MTA_REASON, "Invalid recipient address: no such user", 0, 0);