IABContainer::ResolveNames

Статья
04/04/2023

Область применения: Outlook 2013 | Outlook 2016

Выполняет разрешение имен для одной или нескольких записей получателя.

HRESULT ResolveNames(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  LPADRLIST lpAdrList,
  LPFlagList lpFlagList
);

Параметры

lpPropTagArray

[в] Указатель на структуру SPropTagArray , содержащую массив тегов свойств, описывающих свойства, которые должны быть включены в структуру ADRLIST , возвращаемую поставщиком. Чтобы запросить набор свойств поставщика по умолчанию, передайте значение NULL в параметре lpPropTagArray .

ulFlags

[в] Битовая маска флагов, управляющая типом текста в возвращаемых строках. Можно задать следующие флаги:

EMS_AB_ADDRESS_LOOKUP

Будут найдены только точные совпадения с адресом прокси-сервера; частичные совпадения игнорируются. Этот флаг поддерживается только поставщиком адресной книги Exchange.

MAPI_CACHE_ONLY

Для разрешения имен будет использоваться только автономная адресная книга. Например, этот флаг можно использовать, чтобы клиентское приложение открывало глобальный список адресов (GAL) в режиме кэшированного обмена и открывало запись в этой адресной книге из кэша без создания трафика между клиентом и сервером. Этот флаг поддерживается только поставщиком адресной книги Exchange.

MAPI_UNICODE

Возвращаемые свойства строки имеют формат Юникода. Если флаг MAPI_UNICODE не задан, строки имеют формат ANSI.

lpAdrList

[вход, выход] Во входных данных — указатель на структуру ADRLIST , содержащую список получателей для разрешения. В выходных данных — указатель на структуру ADRLIST , содержащую разрешенные имена.

lpFlagList

[вход, выход] Указатель на массив флагов, каждый из которых соответствует структуре ADRENTRY в параметре lpAdrList , который предоставляет состояние операции разрешения имен для получателя. Флаги в параметре lpFlagList находятся в том же порядке, что и записи в lpAdrList. Можно задать следующие флаги:

MAPI_AMBIGUOUS

Соответствующий получатель разрешен, но не по уникальному идентификатору записи. Другие контейнеры не должны пытаться разрешить этот получатель.

MAPI_RESOLVED

Соответствующий получатель был разрешен в уникальный идентификатор записи. Другие контейнеры не должны пытаться разрешить этот получатель.

MAPI_UNRESOLVED

Соответствующая запись не разрешена. Другие контейнеры должны попытаться разрешить этот получатель.

Возвращаемое значение

S_OK

Процесс разрешения имен прошел успешно.

MAPI_E_BAD_CHARWIDTH

Либо был установлен флаг MAPI_UNICODE и реализация не поддерживает Юникод, либо MAPI_UNICODE не задан и реализация поддерживает только Юникод.

MAPI_E_NO_SUPPORT

Поставщик адресной книги не поддерживает массовое разрешение имен с помощью этого метода.

Замечания

Метод ResolveNames пытается сопоставить неразрешенных получателей из массива записей в параметре lpAdrList с получателями в этом контейнере адресной книги. Неразрешенный получатель обычно имеет только свойство PR_DISPLAY_NAME (PidTagDisplayName) и, возможно, несколько других свойств. Неразрешенный получатель не имеет свойства PR_ENTRYID (PidTagEntryId), а соответствующий флаг в параметре lpFlagList имеет значение MAPI_UNRESOLVED. И наоборот, разрешенный получатель всегда имеет по крайней мере свойство PR_ENTRYID плюс несколько других свойств, таких как PR_EMAIL_ADDRESS (PidTagEmailAddress), PR_DISPLAY_NAME и PR_ADDRTYPE (PidTagAddressType).

Разрешение имен обычно начинается, когда клиент вызывает метод IAddrBook::ResolveName . Outlook MAPI отвечает, вызывая метод ResolveNames каждого контейнера адресной книги, включенного в путь поиска адресной книги , заданный свойством PR_AB_SEARCH_PATH (PidTagAbSearchPath). Записи в параметре lpAdrList включают уже разрешенных получателей, так как они находятся в контейнерах, для которых MAPI уже назвал ResolveNames, так как записи отображаются ранее в пути поиска.

Каждый контейнер пытается разрешить неразрешенные записи, сопоставляя отображаемое имя получателя с отображаемым именем одной из его записей. При обнаружении уникального совпадения ResolveNames добавляет свойство PR_ENTRYID и другие свойства, включенные в параметр lpPropTagArray , в соответствующую запись в исходящей структуре ADRLIST . Затем ResolveNames задает для записи в параметре lpFlagList значение MAPI_RESOLVED. Идентификатор записи, хранящийся в свойстве PR_ENTRYID , может быть краткосрочным или долгосрочным.

После того как все контейнеры в пути поиска попытаются выполнить процесс разрешения имен, MAPI открывает диалоговое окно, если это возможно, чтобы предложить пользователю помощь в разрешении оставшихся конфликтов.

Клиенты также могут использовать возвращаемую структуру ADRLIST в вызовах метода IMessage::ModifyRecipients .

Примечания для исполнителей

Поддержка разрешения имен с помощью метода ResolveNames не требуется. Вместо этого или дополнительно его можно поддерживать с помощью ограничения свойства PR_ANR (PidTagAnr). Если вы решили использовать ограничение PR_ANR для разрешения имен, вы можете вернуть MAPI_E_NO_SUPPORT. For more information, see �� .

Задайте для записи флага получателя в параметре lpFlagList значение MAPI_UNRESOLVED, если получатель не соответствует ни одному из получателей контейнера.

Если получатель совпадает с несколькими получателями, установите для его флага значение MAPI_AMBIGUOUS и не изменяйте структуру ADRENTRY .

MAPI требует определенных свойств для получателей, включенных в список получателей сообщения. Вы можете включить их в структуру ADRENTRY в рамках процесса разрешения имен или дождаться, пока MAPI запросит их с помощью вызовов методов IAddrBook::P repareRecips и IMAPISupport::ExpandRecips . Вы можете исключить эти дополнительные вызовы и повысить производительность, включив следующие свойства в структуры ADRENTRY всех разрешенных получателей:

PR_ADDRTYPE
PR_DISPLAY_NAME
PR_EMAIL_ADDRESS
PR_ENTRYID
PR_OBJECT_TYPE (PidTagObjectType)
PR_SEARCH_KEY (PidTagSearchKey)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)

Если некоторые свойства в параметре lpPropTagArray недоступны (как правило, потому, что запись контейнера не поддерживает свойства и они не включены в элемент ADRENTRY получателя в структуре ADRLIST ), задайте для свойства тип каждого недоступного свойства значение PT_ERROR.

Не удаляйте свойства из структуры ADRENTRY разрешенного получателя.

Если необходимо заменить, а не изменять структуру ADRENTRY , сначала освободите исходную структуру ADRENTRY , вызвав функцию MAPIFreeBuffer , а затем выделите замену структуры ADRENTRYс помощью MAPIAllocateBuffer.