PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Return a message to its originator.

VMS FORMAT

status = PMDF_return_message

(dq_context, channel, from, bad_addresses)

C FORMAT

status = PMDFreturnMessage

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

int PMDFreturnMessage (dq_context, channel, channel_len, 
                       from, from_len, bad_addresses) 
         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 PMDF_dequeue_initialize.

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 PMDF_get_message and must not exceed ALFA_SIZE bytes.

from_len

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

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 PMDF_recipient_disposition routine to stipulate the disposition of each recipient address. Then, when PMDF_dequeue_message_end or PMDF_dequeue_message 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 PMDF_return_message do not adhere to the NOTARY specifications. Messages may be returned to their originator with PMDF_return_message. Messages will be returned in behalf of the channel specified. If no channel name is specified (channel has zero length), then PMDF_return_message 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, PMDF_dequeue_message_end should be called after calling PMDF_return_message. PMDF_return_message 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 PMDF_return_message.