PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Associate a To:, Cc:, or Bcc: address with a message.

VMS FORMAT

status = PMDF_add_recipient

(nq_context, address, orig_address)

C FORMAT

status = PMDFaddRecipient

(nq_context, address, address_len, orig_address, orig_address_len)

int PMDFaddRecipient (nq_context, address, address_len, 
                      orig_address, orig_address_len) 
         PMDF_nq **nq_context; 
         char     *address; 
         int       address_len; 
         char     *orig_address; 
         int       orig_address_len; 

ARGUMENTS

nq_context

A message enqueue context created with PMDF_start_message_envelope.

address

The To:, Cc:, or Bcc: address to associate with the message. The length of the address may not exceed ALFA_SIZE bytes.

address_len

The length in bytes of address.

orig_address

If known, the original form of the input address, address. Length may not exceed ALFA_SIZE bytes.

orig_address_len

Length in bytes of the original address. Supply a value of zero if the original address is not known.

DESCRIPTION

When enqueuing a mail message, the list of To:, Cc:, and Bcc: recipients is built up, one address at a time, by repeatedly calling PMDF_add_recipient. This information is then used to construct the message's envelope To: address list as well as the To:, Cc:, and Bcc: header lines which will appear in the message's header. Note that in the message envelope, there is no distinction between To:, Cc:, and Bcc: addresses. The routine PMDF_set_recipient_type is used to specify whether each address is a To:, Cc:, or Bcc: address and whether or not it should be included in the message's envelope To: address list. PMDF_set_recipient_type should be called prior to PMDF_add_recipient; that is, PMDF_set_recipient_type sets information for the next recipient added with PMDF_add_recipient. If PMDF_set_recipient_type is never called, then each address will be treated as a To: address and added to the message's list of envelope To: addresses. The routine PMDF_set_recipient_flags is used to specify NOTARY flags for a envelope To: address. PMDF_set_recipient_flags should be called prior to PMDF_add_recipient. If PMDF_set_recipient_flags is never called, then each address will be assume the NOTARY flags PMDF_RECEIPT_FAILURES and PMDF_RECEIPT_DELAYS. After calling PMDF_start_message_envelope, PMDF_add_recipient should be called once for each forward pointing address (To:, Cc:, or Bcc:) to be specified. Each address should conform to RFC 822. PMDF will do its best to transform non-conformant addresses into legal RFC 822 addresses; however, this is not always possible and a PMDF:HOST or PMDF:PARSE error may result. After all addresses have been specified, then PMDF_start_message_header should be called, after which no more addresses may be specified for the current message. While multiple addresses, separated by commas, may be passed in a single call, specifying one address per call is recommended: when multiple addresses are specified and an error results, it is not possible to determine which address was in error. Note also that the same address may be specified more than once. This may or may not result in multiple copies of the message being sent to that address. PMDF itself will attempt to deliver a copy of the message to each instance of a specified address; however, some mail systems receiving the mail may only deliver a single copy of the message to each recipient, regardless of how many times a recipient appears in the envelope To: address list (e.g., VMS MAIL).