IABContainer::ResolveNames

The IABContainer::ResolveNames method performs name resolution for one or more recipient entries.

Quick Info

See IABContainer : IMAPIContainer1FQGP0E

HRESULT ResolveNames(

Parameters

lpPropTagArray

[in] Pointer to an SPropTagArray.LHV0L structure containing an array of property tags describing the properties to be included in the ADRLIST structure returned by the provider. To request the provider s default set of properties, pass NULL in the lpPropTagArray parameter.

ulFlags

[in] Bitmask of flags that controls the type of the text in returned strings. The following flag can be set:

MAPI_UNICODE

The returned string properties are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lpAdrList

[in, out] On input, pointer to an ADRLIST16760YG structure containing the list of recipients to be resolved. On output, pointer to an ADRLIST structure containing the resolved names.

lpFlagList

[in, out] Pointer to an array of flags; each flag corresponding to an ADRENTRY structure in the lpAdrList parameter, that provides the status of the name resolution operation for the recipient. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:

MAPI_AMBIGUOUS

The corresponding recipient has been resolved, but not to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_RESOLVED

The corresponding recipient has been resolved to a unique entry identifier. Other containers should not try to resolve this recipient.

MAPI_UNRESOLVED

The corresponding entry has not been resolved. Other containers should try to resolve this recipient.

Return Values

S_OK

The name resolution process was successful.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

MAPI_E_NO_SUPPORT

The address book provider does not support bulk name resolution using this method.

Remarks

The IABContainer::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 only has the PR_DISPLAY_NAME1KS30YA property and possibly a few other properties. An unresolved recipient does not have the PR_ENTRYID2JH9H8T 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, PR_DISPLAY_NAME, and PR_ADDRTYPE.

The name resolution typically beings when a client calls IAddrBook::ResolveNameCDLOVB. MAPI responds by calling the IABContainer::ResolveNames method of each address book container that is included in the address book search path   the PR_AB_SEARCH_PATH1S6K_MO property. The entries in the lpAdrList parameter include recipients already resolved by containers that have already been called because they appear earlier in the search path and unresolved recipients.

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 included in the lpPropTagArray parameter to the corresponding entry in the outgoing ADRLIST16760YG structure and 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 launches a dialog box, if possible, to prompt the user for help in setting any remaining conflicts.

Clients can also use the returned ADRLIST in calls to the IMessage::ModifyRecipientsBTAS42 method.

Notes to Implementers

You are not required to support name resolution with the IABContainer::ResolveNames method. Instead, or in addition, you can support it with the PR_ANR49QUH6 property restriction. If you choose to rely on the PR_ANR restriction for name resolution, you can return MAPI_E_NO_SUPPORT from IABContainer::ResolveNames. For more information, see Implementing the PR_ANR Property Restriction2FRW.WV.

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 alter its ADRENTRYWLHOWG structure.

MAPI requires certain properties on 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 during the processing of IAddrBook::PrepareRecips5NOUT_ and IMAPISupport::ExpandRecips1_1QX1N. Eliminate these extra calls and improve performance by including the following properties in the ADRENTRY structures of all resolved recipients:

PR_ADDRTYPE7C7E4S

PR_DISPLAY_NAME1KS30YA

PR_EMAIL_ADDRESSJ.C5HA

PR_ENTRYID2JH9H8T

PR_OBJECT_TYPE4YLDI0

PR_SEARCH_KEY_7GFC6

PR_TRANSMITTABLE_DISPLAY_NAMEZFDYGM

If some of the properties in the lpPropTagArray parameter are unavailable   typically because the container entry does not support them 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 need to replace rather than modify an ADRENTRY structure, free the original ADRENTRY structure first by calling the MAPIFreeBuffer16U06F function and then allocate the replacement ADRENTRY structure with MAPIAllocateBuffer1MW3BAZ.

See Also