The IABContainer::ResolveNames method performs name resolution for one or more recipient entries.
See IABContainer : IMAPIContainer.
HRESULT ResolveNames(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
LPADRLIST lpAdrList,
LPFlagList lpFlagList
);
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.
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:
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.
ADRENTRY, ADRLIST, IAddrBook::PrepareRecips, IAddrBook::ResolveName, IMAPISupport::ExpandRecips, IMessage::ModifyRecipients, PR_ANR, SPropertyRestriction