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

PASCAL

status = PMDF_add_recipient

(nq_context, address, orig_address)

argument information

Argument	Data type	Access	Mechanism
nq_context	context pointer	read/write	reference
address	descriptor	read	reference
orig_address	descriptor	read	reference

C

status = PMDFaddRecipient

(nq_context, address, address_len, orig_address, orig_address_len)

argument information

int PMDFaddRecipient(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 PMDFstartMessageEnvelope .

address

The "To:", "Cc:", or "Bcc:" address to associate with the message. The length of the address can 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 can 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 PMDFaddRecipient . 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 PMDFsetRecipientType 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. PMDFsetRecipientType should be called prior to PMDFaddRecipient ; that is, PMDFsetRecipientType sets information for the next recipient added with PMDFaddRecipient . If PMDFsetRecipientType 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 PMDFsetRecipientFlags is used to specify NOTARY flags for a envelope "To:" address. PMDFsetRecipientFlags should be called prior to PMDFaddRecipient . If PMDFsetRecipientFlags is never called, then each address will be assume the NOTARY flags PMDF_RECEIPT_FAILURES and PMDF_RECEIPT_DELAYS. After calling PMDFstartMessageEnvelope , PMDFaddRecipient 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 can result. After all addresses have been specified, then PMDFstartMessageHeader should be called, after which no more addresses can be specified for the current message. While multiple addresses, separated by commas, can 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 can be specified more than once. This can or can 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 can 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).

Return Values

PMDF__OK	Successful, normal completion.
PMDF__BADCONTEXT	Illegal or corrupt context. No address added.
PMDF__HOST	Illegal address. No address added. Call PMDFgetErrorText to obtain specific information about the nature of the error.
PMDF__INVSTRDES	Invalid string descriptor for address: descriptor has an invalid value in its DSC$B_CLASS field. No address added.
PMDF__NAUTH	Sender is not authorized to send to this address or mailing list. No address added. Call PMDFgetErrorText to obtain specific information about the nature of the error.
PMDF__PARSE	Bad address syntax. No address added. Call PMDFgetErrorText to obtain specific information about the nature of the error.
PMDF__STRTRUERR	Length of address exceeds ALFA_SIZE bytes. No address added.
PMDF__USER	Unknown or illegal user name specification. No address added. Call PMDFgetErrorText to obtain specific information about the nature of the error.