IAddrBook::PrepareRecips

The IAddrBook::PrepareRecips method prepares a recipient list for later use by the messaging system.

Quick Info

HRESULT PrepareRecips(
  ULONG ulFlags,                     
  LPSPropTagArray lpSPropTagArray,   
  LPADRLIST lpRecipList              
);

Parameters

ulFlags: Reserved; must be zero.
lpSPropTagArray: [in] Pointer to an SPropTagArray structure containing an array of property tags indicating properties that require updating, if any. The lpSPropTagArray parameter can be NULL.
lpRecipList: [in] Pointer to an ADRLIST structure holding the list of recipients.

Return Values

S_OK: The recipient list was successfully prepared.

Remarks

Clients and service providers call the IAddrBook::PrepareRecips method to:

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 beginning 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 along with any additional properties requested.

Within an individual recipient entry, the requested properties are ordered first, followed by any additional properties that were already present for the entry. If one or more of the requested properties, the properties included in the lpSPropTagArray, are not handled by the appropriate address book provider, their property types will be set to PT_ERROR and their property values either to MAPI_E_NOT_FOUND or to another value giving a more specific reason why the properties are not available. Each SPropValue structure included in the lpSPropTagArray parameter must be separately allocated using the MAPIAllocateBuffer and MAPIAllocateMore functions such that it can be freed individually.

For information on PT_ERROR, see List of Property Types.