PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Obtain the next envelope To: address from a message.

VMS FORMAT

status = PMDF_get_recipient

(dq_context, address, address_len, orig_address, orig_address_len)

C FORMAT

status = PMDFgetRecipient

(dq_context, address, address_len, orig_address, orig_address_len)

int PMDFgetRecipient (dq_context, address, address_len, 
                      orig_address, orig_address_len) 
         PMDF_dq **dq_context; 
         char     *address; 
         int      *address_len; 
         char     *orig_address; 
         int      *orig_address_len; 

ARGUMENTS

dq_context

A message dequeue context created with PMDF_dequeue_initialize.

address

String to receive an envelope To: address from the message's envelope. Length must be at least ALFA_SIZE bytes. (ALFA_SIZE+1 bytes for PMDFgetRecipient.)

address_len

Length in bytes of the envelope To: address. Callers using PMDFgetRecipient must, on input, supply the maximum length in bytes of address.

orig_address

String to receive the original form of the envelope To: address, if known. Length must be at least ALFA_SIZE bytes. (ALFA_SIZE+1 bytes for PMDFgetRecipient.)

orig_address_len

Length in bytes of the original envelope To: address, if known. Callers using PMDFgetRecipient must, on input, supply the maximum length in bytes of orig_address.

DESCRIPTION

PMDF_get_recipient should be called repeatedly to obtain each envelope To: address from a message. In each call to PMDF_get_recipient a single envelope To: address will be returned in address. After all addresses have been output, PMDF_get_recipient will return the status code PMDF__EOF. For example, if the message envelope has two To: addresses, then three calls to PMDF_get_recipient should be made. In the first two calls, the two addresses will be output along with the return status code PMDF__OK. In the third call no address will be output and the status code PMDF__EOF will be returned. After each call in which PMDF_get_recipient returns PMDF:OK, a call should be made to PMDF_get_recipient_flags to obtain the NOTARY processing flags associated with the envelope To: address. After all of the envelope To: addresses have been read, the message header and body may be read with PMDF_read_header, PMDF_read_line, and PMDF_read_text. The orig_address gives, if known, the original form of the envelope To: address. This is original address is carried with the message and used when generating notifications concerning the message. When calling PMDF_recipient_disposition or re-enqueuing a message to PMDF, this original address should be supplied. After the channel processes an envelope To: address and determines its disposition, PMDF_recipient_disposition must be called. The NOTARY flag obtained with PMDF_get_recipient_flags for that address as well the original form of the address must be supplied to PMDF_recipient_disposition. By supplying this disposition information, PMDF can automatically generate determine whether or not the message needs to be deferred for later processing and generate any required notifications when the message being dequeued is de-accessed. If the status code PMDF:NO is returned, then the message file was found to be missing both a message header and message body and has been deleted. The calling program should abort processing of the current message and call either PMDF_dequeue_message_end with the defer argument set to true. If the status code PMDF:STRTRU is returned, then it is probably not safe to proceed: the envelope To: address had to be truncated to fit into the supplied address string and a truncated address is generally worthless.