Last modified: July 23, 2011
Applies to: Outlook
Performs name resolution for one or more recipient entries.
The 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 has only the PR_DISPLAY_NAME (PidTagDisplayName) property and possibly a few other properties. An unresolved recipient does not have the PR_ENTRYID (PidTagEntryId) 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 (PidTagEmailAddress), PR_DISPLAY_NAME, and PR_ADDRTYPE (PidTagAddressType).
Name resolution typically starts when a client calls the IAddrBook::ResolveName method. Outlook MAPI responds by calling the ResolveNames method of each address book container included in the address book search path, specified by the PR_AB_SEARCH_PATH (PidTagAbSearchPath) property. The entries in the lpAdrList parameter include recipients already resolved because they are in containers for which MAPI has already called ResolveNames, because the entries appear earlier in the search path.
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 that are included in the lpPropTagArray parameter to the corresponding entry in the outgoing ADRLIST structure. ResolveNames then 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 opens 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 ResolveNames method. Instead, or additionally, you can support it with the PR_ANR (PidTagAnr) property restriction. If you decide to rely on the PR_ANR restriction for name resolution, you can return MAPI_E_NO_SUPPORT. 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 change its ADRENTRY structure.
MAPI requires certain properties for 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 with calls to the IAddrBook::PrepareRecips and IMAPISupport::ExpandRecips methods. You can 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 the properties 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 must 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.