IAddrBook::ResolveName

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Performs name resolution, assigning entry identifiers to recipients in a recipient list.

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

Parameters

• ulUIParam
  [in] A handle to the parent window of a dialog box that is shown, if specified, to prompt the user to resolve ambiguity.

• ulFlags
  [in] A bitmask of flags that control various aspects of the resolution process. The following flags can be set:

  • AB_UNICODEUI
    Indicates that lpszNewEntryTitle is a UNICODE string.

  • MAPI_CACHE_ONLY
    Use only the offline address book to perform name resolution. For example, you can use this flag to allow a client application to open the global address list (GAL) in cached exchange mode and access an entry in that address book from the cache without creating traffic between the client and the server. This flag is supported only by the Exchange Address Book Provider.

  • MAPI_DIALOG
    Displays 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] A 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] A pointer to an ADRLIST structure that contains the list of recipient names to be resolved. This ADRLIST structure can be created by the IAddrBook::Address method.

Return Value

• 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 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 (PidTagEntryId) property.

ResolveName goes through the following process for each unresolved entry in the address list passed in the lpAdrList parameter.

1. If the address type of the recipient adheres to the format of an SMTP address (displayname@domain.top-level-domain), ResolveName assigns it a one-off entry identifier.

2. For each container in the PR_AB_SEARCH_PATH (PidTagAbSearchPath) property, ResolveName calls the IABContainer::ResolveNames method. ResolveNames tries to match the display name of each unresolved recipient with a display name that belongs to one of its entries.

3. If a container does not support ResolveNames, ResolveName restricts the container's contents table by using a PR_ANR (PidTagAnr) 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.

4. When a container returns a recipient that matches multiple names, ResolveName displays a dialog box if the MAPI_DIALOG flag is set, which lets the user select the correct name.

5. 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, ResolveName returns MAPI_E_NOT_FOUND. If one or more recipients had ambiguous resolution that could not be resolved with a dialog box, or because the MAPI_DIALOG flag was not set, ResolveName returns MAPI_E_AMBIGUOUS_RECIP. When some of the recipients are ambiguous and some cannot be resolved, ResolveName can return either error value.

If a name cannot be resolved, the client can create a one-off address that has 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; if you set the MAPI_UNICODE flag, the following properties are returned as type PT_UNICODE in the ADRENTRY structures:

• PR_ADDRTYPE (PidTagAddressType)

• PR_DISPLAY_NAME (PidTagDisplayName)

• PR_EMAIL_ADDRESS (PidTagEmailAddress)

• PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)

However, the PR_7BIT_DISPLAY_NAME (PidTag7BitDisplayName) property is always returned as type PT_STRING8.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
MAPIABFunctions.cpp	AddOneOffAddress	MFCMAPI uses the ResolveName method to resolve a one-off address before adding it to a message.
MAPIABFunctions.cpp	AddRecipient	MFCMAPI uses the ResolveName method to look up an address book entry by display name.

See Also

Reference

ADRLIST

IABContainer::ResolveNames

IAddrBook::Address

IAddrBook : IMAPIProp

Concepts

MFCMAPI as a Code Sample