Remove a message from PMDF's message queues.

PASCAL

status = PMDF_dequeue_message_end

(dq_context, defer, reason)

C

status = PMDFdequeueMessageEnd

(dq_context, defer, reason, reason_len)

int PMDFdequeueMessageEnd(PMDF_dq **dq_context, int defer, char *reason, int reason_len)

Arguments

dq_context

A message dequeue context created with PMDFdequeueInitialize.

defer

When true (1), the message will be deferred for later processing.

reason

Optional text string describing why the message is being deferred. The length of this string should not exceed BIGALFA_SIZE bytes.

reason_len

Length in bytes of reason.

Description

NOTE: Use of this routine with defer set to false (0) requires that PMDFrecipientDisposition be called for each recipient address obtained with PMDFgetRecipient. To finish processing a message, call PMDFdequeueMessageEnd. This will re-enqueue the message if it requires deferred processing of some or all of its recipients as well as generate any required notification messages concerning the message. Specifically, if all recipient addresses have a permanent disposition (PMDF_DISP_DELIVERED, _FAILED, _RELAYED, _RELAYED_FOREIGN, or _RETURN) then any required notifications are generated and the message is permanently removed from the processing queue. If all recipients are to be deferred (PMDF_DISP_DEFERRED), then no notifications are generated and the message is left in the queue for later re-processing. If some recipients have a permanent disposition while others were deferred, then

1. Any required notifications are generated for those recipients with permanent dispositions,
2. A new message is enqueued for just those recipients who were deferred, and
3. The original message file is removed from the processing queue.

A message can be forcibly deferred, without regard to the dispositions of the recipients, by passing a value of true (1) for the defer argument. When a message is deferred, either because defer is true or all recipients have a deferred disposition, then the value supplied with the reason argument will be placed in the message's delivery failure log. If a zero length string is supplied for that argument, then the deferral reason, if any, for the last deferred recipient address will be used. Should the message be returned as an undeliverable message by PMDF's message return system, a copy of the log will be included with the returned message.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__BADCONTEXT	Illegal or corrupt context. Message not dequeued.