[in] Handle of the parent window for a dialog box that is shown, if necessary, to prompt the user to resolve ambiguity.
ulFlags
[in] Bitmask of flags that control various aspects of the resolution process. The following flags can be set:
MAPI_DIALOG
Allows the display of a dialog box to prompt the user for additional name resolution information. If this flag is not set, no dialog box is displayed.
MAPI_UNICODE
Indicates that the properties returned in the address list should be of type PT_UNICODE instead of PT_STRING8.
lpszNewEntryTitle
[in] Pointer to text for the title of the control in the dialog box that prompts the user to enter a recipient. The title varies depending on the type of recipient. The lpszNewEntryTitle parameter can be NULL.
lpAdrList
[in-out] Pointer to an ADRLIST structure containing the list of recipient names to be resolved. This ADRLIST structure can be created by the IAddrBook::Address method.
Return Values
S_OK
The name resolution process succeeded.
MAPI_E_AMBIGUOUS_RECIP
At least one recipient in the lpAdrList parameter matched more than one entry in the address book. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.
MAPI_E_NOT_FOUND
At least one recipient in the lpAdrList parameter cannot be resolved. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.
Remarks
Clients and service providers call the IAddrBook::ResolveName method to initiate the name resolution process. An unresolved entry is an entry that does not yet have an entry identifier — or PR_ENTRYID property.
ResolveName goes through the following process for each unresolved entry in the address list passed in the lpAdrList parameter:
If the address type of the recipient adheres to the format of an SMTP address (displayname@address.addresslist), IAddrBook::ResolveName assigns it a one-off entry identifier.
For each container in the PR_AB_SEARCH_PATH property, IAddrBook::ResolveName calls the IABContainer::ResolveNames method. IABContainer::ResolveNames tries to match the display name of each unresolved recipient with a display name belonging to one of its entries.
If a container does not support IABContainer::ResolveNames, IAddrBook::ResolveName restricts the container's contents table using a PR_ANR property restriction. This restriction causes the container to perform a "best guess" type of search to locate a matching recipient. All containers must support the PR_ANR property restriction.
When a container returns a recipient that matches multiple names, IAddrBook::ResolveName displays a dialog box — if the MAPI_DIALOG flag is set — allowing the user to select the correct name.
If all of the containers in the PR_AB_SEARCH_PATH property have been called and no match has been found, the recipient remains unresolved.
If one or more recipients are unresolved, IAddrBook::ResolveName returns MAPI_E_NOT_FOUND. If one or more recipients had ambiguous resolution that could not be resolved with a dialog box because the MAPI_DIALOG flag was not set, IAddrBook::ResolveName returns MAPI_E_AMBIGUOUS_RECIP. When some of the recipients are ambiguous and some cannot be resolved, IAddrBook::ResolveName can return either error value.
If a name cannot be resolved, the client can create a one-off address with a specially formatted address and entry identifier. For more information about the format of one-off entry identifiers, see One-Off Entry Identifiers. For more information about the format of one-off addresses, see One-Off Addresses.
MAPI supports Unicode character strings for the ADRLIST and the new entry title parameters to ResolveName on Windows NT platforms only. If you set the MAPI_UNICODE flag, the following properties are returned as type PT_UNICODE in the ADRENTRY structures: