Creating a Recipient List

A recipient list is an ADRLIST structure that contains an array of property value structures for each message recipient — destination for the message. A recipient can represent a human user, a machine, or a folder. All messages to be sent require at least one recipient that has been through the name resolution process — a process for ensuring that the PR_ENTRYID property is included in the recipient's property value array.

The properties of a recipient are a combination of address book properties and message properties. Recipient properties can apply either to all messages for a particular recipient or only to the current message. Both message store and transport providers can set recipient properties.

Each recipient must have a core set of properties in its property value array by the time the message is ready to be sent. The required set of recipient properties include:

PR_ADDRTYPE

PR_DISPLAY_NAME

PR_EMAIL_ADDRESS

PR_ENTRYID

PR_OBJECT_TYPE

PR_SEARCH_KEY

These properties are used to access the recipient, send messages to it, and to compare it to others. Not all of these properties need to be available right away. You can add a recipient initially without knowing its entry identifier, relying on the name resolution process to assign this property. At some point before you send a message, call IAddrBook::ResolveName to make sure that all of the recipients in your recipient list are resolved. For more information about resolving recipients, see Resolving a Name.

Recipient lists can be created from messaging users or distribution list entries in an address book container or from one-offs. One-offs are recipients that are created either as temporary entries to be used only for addressing a single message or as entries to be added to a personal address book. The format for a one-off entry identifier and address is defined by MAPI. For information about these formats, see One-Off Addresses and One-Off Entry Identifiers.

You can allow users to build their recipient lists:

• Only with entries from the address book.
• Only with one-off entries.
• With a combination of address book recipients and one-offs.

To create a recipient list using the common address dialog box

1. Allocate an ADRPARM structure and a pointer to an ADRLIST structure.
2. Zero the memory in the ADRPARM structure and set the ADRLIST pointer to NULL.
3. Call IAddrBook::Address to display the address dialog box and populate the ADRPARM structure.
4. Call IMessage::ModifyRecipients, passing the ADRLIST pointer. This structure will contain the properties of each of the recipients selected by the user.

To create a recipient list programmatically

1. Allocate an ADRLIST structure that contains one ADRENTRY structure for each of the recipients to be included in the list. Make each ADRENTRY structure large enough to hold each of the required properties and PR_RECIPIENT_TYPE.
2. For each recipient, set the property value array for its aEntries member in the ADRLIST structure. For example, the following code sample shows how to include the entry identifier and display name in the array.

LPADRLIST lpAdrList = NULL;

hr = MAPIAllocateBuffer(numProps * sizeof(SPropValue), 
                (LPVOID FAR *(&lpAdrList->aEntries[0].rgPropVals);

lpAdrList->aEntries[0].rgPropVals[0].ulPropTag = PR_ENTRYID;
lpAdrList->aEntries[0].rgPropVals[0].Value.bin     = RecipEID;

lpAdrList->aEntries[0].rgPropVals[1].ulPropTag = PR_DISPLAY_NAME;
lpAdrList->aEntries[0].rgPropVals[1].Value.LPSZ     = szDisplay;

lpAdrList->aEntries[0].cValues=numProps;
 

3. Call IMessage::ModifyRecipients with the MODRECIP_ADD flag set.