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:
1. 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.
2. 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.
3. 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.
4. 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.
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, 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.
See Also