IAddrBook::ResolveName

The IAddrBook::ResolveName method performs name resolution, assigning entry identifiers to recipients in a recipient list.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT ResolveName(
  ULONG ulUIParam,            
  ULONG ulFlags,              
  LPTSTR lpszNewEntryTitle,   
  LPADRLIST lpAdrList         
);

Parameters

ulUIParam

[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 controls whether a dialog box can be displayed. The following flag 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.

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.