| Platform SDK: MAPI |
A client application prepares recipients by converting their short-term entry identifiers to long-term entry identifiers and possibly adding, changing, or reordering properties. You can prepare recipients that are part of a recipient list for a message or recipients that are unrelated to a message. Typically, clients call IAddrBook::PrepareRecips directly to translate short-term entry identifiers into long-term entry identifiers for recipients that are included in the common address dialog box. For recipients that are associated with an outgoing message, recipient preparation is handled by the name resolution process.
To prepare a list of recipients, call IAddrBook::PrepareRecips. PrepareRecips accepts an ADRLIST structure and a list of property tags. The ADRLIST structure contains the recipients to be prepared while the property tag list represents properties that each recipient should support. PrepareRecips attempts to place the properties that are included in the property tag list at the beginning of the ADRLIST structure. If any of the properties in the list are missing from the ADRLIST structure, MAPI calls the address book provider to supply them. If you only need to check for long-term entry identifiers, pass NULL for the lpSPropTagArray parameter.
For example, suppose you are working with five recipients. All five recipients appear in the ADRLIST structure with the following properties in the following order:
Three other properties are included in the ADRLIST structure for the first two recipients.
Because all of the recipients need to have as their first three properties PR_ADDRTYPE, PR_ENTRYID, and PR_HOME_TELEPHONE_NUMBER, create a property tag array with these properties and pass it and the ADRLIST structure to PrepareRecips. PrepareRecips calls each recipient's IMAPIProp::GetProps method to retrieve PR_HOME_TELEPHONE_NUMBER because it is not currently part of the ADRLIST structure. When PrepareRecips returns, the recipient list represents a merged list of recipients with the properties included in the ADRLIST structure appearing first for each recipient.
The recipient list for recipients 1 and 2 includes properties in the following order:
The recipient list for recipients 3, 4, and 5 includes properties in the following order:
As an alternative to calling IAddrBook::PrepareRecips to work with properties, call each recipient's IMAPIProp::GetProps method and, if necessary, its IMAPIProp::SetProps method. When only one recipient is involved, either technique is satisfactory. However, when multiple recipients are involved, calling PrepareRecips rather than the IMAPIProp methods saves time and, if you are operating remotely, many remote procedure calls. PrepareRecips processes all recipients in a single call whereas GetProps and SetProps make one call for each recipient.