Return a message to its originator.

PASCAL

status = PMDF_return_message

(dq_context, channel, from, bad_addresses)

C

status = PMDFreturnMessage

(dq_context, channel, channel_len, from, from_len, bad_addresses)

int PMDFreturnMessage(PMDF_dq **dq_context, char *channel, int channel_len, char *from, int from_len, PMDF_item_list *bad_addresses)

Arguments

dq_context

A message dequeue context created with PMDFdequeueInitialize.

channel

Name of the channel to act in behalf of when bouncing the message. The length of channel must not exceed CHANLENGTH bytes.

channel_len

Length in bytes of channel.

from

Envelope "From:" address associated with the message to be returned. This string was returned by PMDFgetMessage and must not exceed ALFA_SIZE bytes.

from_len

Length in bytes of the envelope "From:" address. This value was returned by PMDFgetMessage.

bad_addresses

Item list specifying each bad address along with any error information.

Description

NOTE: While still supported, this routine is now obsolete. Callers should instead use the PMDFrecipientDisposition routine to stipulate the disposition of each recipient address. Then, when PMDFdequeueMessageEnd or PMDFdequeueMessage is called, any necessary notification messages will automatically be generated. Moreover, the notification messages will conform to the NOTARY specifications (RFC 1892, 1893, and 1894). NOTE: The notification messages generated by PMDFreturnMessage do not adhere to the NOTARY specifications. Messages can be returned to their originator with PMDFreturnMessage. Messages will be returned in behalf of the channel specified. If no channel name is specified (channel has zero length), then PMDFreturnMessage will use the name of the currently running channel if possible and the local channel otherwise. In order to remove the returned message from PMDF's message queues, PMDFdequeueMessageEnd should be called after calling PMDFreturnMessage. PMDFreturnMessage will determine from the message's header the most appropriate address to return the message to as well as whether or not to send a copy of the message to the local postmaster (as controlled by channel keywords for the channel the message is being returned in whose behalf). The returned message will be a multipart message containing two parts. The first part contains a list of the bad addresses to which the original message was addressed to. These addresses are given in the item list referenced by bad_addresses. Specifically, the bad_addresses argument is the address of a list of item descriptors, each of which describes a bad address. Each item descriptor has the structure

struct { int reserved1; void *item_address; int reserved2; int item_length; }

item_address is a pointer to a string giving a bad address and any explanation as to why the address was bad; item_length is an integer giving the length of the string pointed at by item_address. The item list is terminated by an entry with an item_length of zero. Each string specified by an entry in the item list is output, one string per line. The strings appear best if in the format:

address - error text

where address is a bad address and error-text is any applicable error message associated with the bad address. The bad addresses are generally envelope "To:" addresses which failed. For example,

a@b.com - mail rejected; no such user 'a@b.com'.

The second part of the multipart message will contain the failed message itself. Examples 1-10 and 1-11 demonstrate the use of PMDFreturnMessage.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__BADCONTEXT	Illegal or corrupt context. Message not returned.
PMDF__INVSTRDES	Invalid string descriptor for channel or from: one or both of the descriptors has an invalid value in its DSC$B_CLASS field. Message not returned.
PMDF__STRTRUERR	One or both of the channel or from strings exceeds the maximum permitted length. Message not returned.