IABLogon::PrepareRecips
The IABLogon::PrepareRecips
method prepares a recipient list for later use by the messaging system.
Quick Info
See IABLogon
: IUnknown.
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
MAPI calls
the IABLogon::PrepareRecips method to:
Ensure that each recipient in
the address list pointed to by lpRecipList has a long-term entry
identifier.
Ensure that all of the
properties in the lpPropTagArray parameter exist in the property value array
included in each recipient s ADRENTRY structure in the ADRLIST.
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.
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.
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.
See Also