IABContainer::ResolveNames

The IABContainer::ResolveNames method performs name resolution for one or more recipient entries.

Quick Info

HRESULT ResolveNames(
  LPSPropTagArray lpPropTagArray,   
  ULONG ulFlags,                    
  LPADRLIST lpAdrList,              
  LPFlagList lpFlagList             
);

Parameters

lpPropTagArray

[in] Pointer to an SPropTagArray structure containing an array of property tags describing the properties to be included in the ADRLIST structure returned by the provider. To request the provider's default set of properties, pass NULL in the lpPropTagArray parameter.

ulFlags

[in] Bitmask of flags that controls the type of the text in the returned strings. The following flag can be set:

MAPI_UNICODE: The returned string properties are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpAdrList

[in, out] On input, pointer to an ADRLIST structure containing the list of recipients to be resolved. On output, pointer to an ADRLIST structure containing the resolved names.

lpFlagList

[in, out] Pointer to an array of flags; each flag corresponding to an ADRENTRY structure in the lpAdrList parameter, that provides the status of the name resolution operation for the recipient. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:

MAPI_AMBIGUOUS: The corresponding recipient has been resolved, but not to a unique entry identifier. Other containers should not try to resolve this recipient.
MAPI_RESOLVED: The corresponding recipient has been resolved to a unique entry identifier. Other containers should not try to resolve this recipient.
MAPI_UNRESOLVED: The corresponding entry has not been resolved. Other containers should try to resolve this recipient.

Return Values

S_OK: The name resolution process was successful.
MAPI_E_BAD_CHARWIDTH: Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
MAPI_E_NO_SUPPORT: The address book provider does not support bulk name resolution using this method.

Remarks

The IABContainer::ResolveNames method attempts to match unresolved recipients from the array of entries in the lpAdrList parameter to recipients in this address book container. An unresolved recipient typically only has the PR_DISPLAY_NAME property and possibly a few other properties. An unresolved recipient does not have the PR_ENTRYID property, and its corresponding flag in the lpFlagList parameter is set to MAPI_UNRESOLVED. Conversely, a resolved recipient always has at least the PR_ENTRYID property plus several other properties such as PR_EMAIL_ADDRESS, PR_DISPLAY_NAME, and PR_ADDRTYPE.

The name resolution typically begins when a client calls IAddrBook::ResolveName. MAPI responds by calling the IABContainer::ResolveNames method of each address book container that is included in the address book search path — the PR_AB_SEARCH_PATH property. The entries in the lpAdrList parameter include recipients already resolved by containers that have already been called because they appear earlier in the search path and unresolved recipients.

Each container attempts to resolve the unresolved entries by matching the display name of the recipient with the display name of one of its entries. When a unique match is found, ResolveNames adds the PR_ENTRYID property and other properties included in the lpPropTagArray parameter to the corresponding entry in the outgoing ADRLIST structure and sets the entry in the lpFlagList parameter to MAPI_RESOLVED. The entry identifier stored in the PR_ENTRYID property can be short-term or long-term.

After all of the containers in the search path have attempted the name resolution process, MAPI launches a dialog box, if possible, to prompt the user for help in resolving any remaining conflicts.

Clients can also use the returned ADRLIST structure in calls to the IMessage::ModifyRecipients method.

Notes to Implementers

You are not required to support name resolution with the IABContainer::ResolveNames method. Instead, or in addition, you can support it with the PR_ANR property restriction. If you choose to rely on the PR_ANR restriction for name resolution, you can return MAPI_E_NO_SUPPORT from IABContainer::ResolveNames. For more information, see Implementing Name Resolution.

Set a recipient's flag entry in the lpFlagList parameter to MAPI_UNRESOLVED if the recipient does not match any of the container's recipients.

When a recipient matches multiple recipients, set its flag to MAPI_AMBIGUOUS and do not alter its ADRENTRY structure.

MAPI requires certain properties on recipients that are included in a message's recipient list. You can include them in the ADRENTRY structure as part of the name resolution process or wait for MAPI to request them during the processing of IAddrBook::PrepareRecips and IMAPISupport::ExpandRecips. Eliminate these extra calls and improve performance by including the following properties in the ADRENTRY structures of all resolved recipients:

PR_TRANSMITTABLE_DISPLAY_NAME

If some of the properties in the lpPropTagArray parameter are unavailable — typically because the container entry does not support them and they are not included in the recipient's ADRENTRY member in the ADRLIST structure — set the property type of each unavailable property to PT_ERROR.

Do not remove any properties from a resolved recipient's ADRENTRY structure.

If you need to replace rather than modify an ADRENTRY structure, free the original ADRENTRY structure first by calling the MAPIFreeBuffer function and then allocate the replacement ADRENTRY structure with MAPIAllocateBuffer.