IAddrBook::PrepareRecips
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Prepares a recipient list for later use by the messaging system.
HRESULT PrepareRecips(
ULONG ulFlags,
LPSPropTagArray lpSPropTagArray,
LPADRLIST lpRecipList
);
Parameters
ulFlags
[in] A bitmask of flags that controls how the entry is opened. The following flag can be set:- MAPI_CACHE_ONLY
Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and to access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.
- MAPI_CACHE_ONLY
lpSPropTagArray
[in] A pointer to an SPropTagArray structure that contains an array of property tags that indicate the properties, if any, that require updating. The lpSPropTagArray parameter can be NULL.lpRecipList
[in] A pointer to an ADRLIST structure that contains the list of recipients.
Return Value
- S_OK
The recipient list was successfully prepared.
Remarks
Clients and service providers call the PrepareRecips method to do the following:
Ensure that all recipients in the lpRecipList parameter have long-term entry identifiers.
Ensure that each recipient in the lpRecipList parameter has the properties listed in the lpSPropTagArray parameter and that these properties appear at the start of the recipient list.
MAPI converts each recipient's short-term entry identifiers to long-term entry identifiers. If necessary, recipients' long-term entry identifiers are retrieved from the appropriate address book provider and any additional properties are requested.
In an individual recipient entry, the requested properties are ordered first, followed by any properties that were already present for the entry. If one or more of the requested properties in the lpSPropTagArray parameter are not handled by the appropriate address book provider, their property types will be set to PT_ERROR. Their property values will be set to either to MAPI_E_NOT_FOUND or to another value that gives a more specific reason why the properties are not available. Each SPropValue structure included in the lpRecipList parameter must be separately allocated by using the MAPIAllocateBuffer and MAPIAllocateMore functions so that it can be freed individually.
For information about PT_ERROR, see Property Types.