IABLogon::PrepareRecips

Platform SDK: MAPI

IABLogon::PrepareRecips

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

Quick Info

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

Parameters

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

Return Values

S_OK: The recipient list was successfully prepared.
MAPI_E_NOT_FOUND: One or more of the recipients in the lpRecipList parameter does not exist.

Remarks

A client calls the MAPI IAddrBook::PrepareRecips method to modify or rearrange a set of properties for one or more recipients. The recipients may or may not be part of the recipient list of an outgoing message. MAPI transfers this call to an address book provider's IABLogon::PrepareRecips method.

PrepareRecips performs four main tasks:

Ensures that all recipients in the address list pointed to by lpRecipList have a long-term entry identifier.
Ensures that all recipients have the properties specified in the property tag array pointed to by lpPropTagArray.
Ensures that the properties from the property tag array appear before any other properties that existed prior to the call.
Ensures that the order of the properties in each recipient's ADRENTRY structure in the ADRLIST structure is the same as in the property tag array.

The ADRLIST structure in the lpRecipList parameter contains one ADRENTRY structure for each recipient. Each ADRENTRY structure contains an array of SPropValue structures to describe the recipient's properties. When PrepareRecips returns, the SPropValue structure array for each recipient includes the properties from the lpPropTagArray followed by the other properties for the recipient.

Notes to Implementers

Implementing PrepareRecips involves placing properties in a specific order, retrieving property values, and converting short-term entry identifiers to long-term entry identifiers. The properties that are included in the lpPropTagArray parameter should appear at the beginning of the property value array associated with each recipient's ADRENTRY structure in the lpRecipList parameter. If values for these properties do not exist, open the associated messaging user or distribution list by using its entry identifier and retrieve the missing property values.

Allocate each SPropValue structure passed in lpPropTagArray separately so that the structures can be freed individually. If you must allocate additional space for any SPropValue structure — for example, to store the data for a string property — use MAPIAllocateBuffer to allocate additional space for the full property tag array. Use the MAPIFreeBuffer function to free the original property tag array and then use MAPIAllocateMore to allocate any additional memory required.

To implement IABLogon::PrepareRecips

Check for entries in the lpPropTagArray parameter. If the property tag array is empty, there is no work to do. Return with a success value.
Process each recipient in the lpRecipList parameter. There is one ADRENTRY structure member for each recipient in the list. Ignore the following types of recipients:
- Recipients without an entry identifier in the rgPropVals member of their ADRENTRY structure, that is, unresolved recipients.
- Recipients with an entry identifier that does not belong to your provider. These recipients will be passed on to another address book provider.
Open the recipient and retrieve the properties already set for the recipient.
Merge the property value array specified in the lpPropTagArray with the array of properties returned from GetProps. If the same property exists in both property arrays, use the value from lpPropTagArray.
If the lpPropTagArray property value array is big enough to hold all of the necessary properties, just replace it with the merged array. If the lpPropTagArray property value array is not big enough, replace it with a newly allocated array. Make sure the new array has an updated value in each of its cValues members.
If you do not recognize one or more of the properties in the lpPropTagArray parameter, set the property type in the recipient's ADRENTRY structure to PT_ERROR and the property value either to MAPI_E_NOT_FOUND or to another value giving a more specific reason for the unavailability. For information about PT_ERROR, see List of Property Types.

Note Never reallocate the ADRLIST structure that is passed into PrepareRecips or change its number of entries.