IAddrBook::ResolveName
Область применения: Outlook 2013 | Outlook 2016
Выполняет разрешение имен, присваивая идентификаторы записей получателям в списке получателей.
HRESULT ResolveName(
ULONG_PTR ulUIParam,
ULONG ulFlags,
LPSTR lpszNewEntryTitle,
LPADRLIST lpAdrList
);
Параметры
ulUIParam
[в] Дескриптор родительского окна диалогового окна, который отображается, если указано, чтобы предложить пользователю устранить неоднозначность.
ulFlags
[в] Битовая маска флагов, управляющих различными аспектами процесса разрешения. Можно задать следующие флаги:
AB_UNICODEUI
Указывает, что lpszNewEntryTitle является строкой ЮНИКОДа.
MAPI_CACHE_ONLY
Используйте только автономную адресную книгу для разрешения имен. Например, этот флаг можно использовать, чтобы разрешить клиентскому приложению открывать глобальный список адресов (GAL) в режиме кэшированного обмена и получать доступ к записи в этой адресной книге из кэша без создания трафика между клиентом и сервером. Этот флаг поддерживается только поставщиком адресной книги Exchange.
MAPI_DIALOG
Отображает диалоговое окно с запросом у пользователя дополнительных сведений о разрешении имен. Если этот флаг не задан, диалоговое окно не отображается.
MAPI_UNICODE
Указывает, что свойства, возвращаемые в списке адресов, должны иметь тип PT_UNICODE, а не PT_STRING8.
lpszNewEntryTitle
[в] Указатель на текст для заголовка элемента управления в диалоговом окне, предлагающий пользователю ввести получателя. Заголовок зависит от типа получателя. Параметр lpszNewEntryTitle может иметь значение NULL.
lpAdrList
[входной выход] Указатель на структуру ADRLIST , содержащую список имен получателей для разрешения. Эту структуру ADRLIST можно создать с помощью метода IAddrBook::Address .
Возвращаемое значение
S_OK
Процесс разрешения имен выполнен успешно.
MAPI_E_AMBIGUOUS_RECIP
По крайней мере один получатель в параметре lpAdrList соответствует нескольким записям в адресной книге. Обычно это значение возвращается при установке флага MAPI_DIALOG, запрещающего отображение диалогового окна.
MAPI_E_NOT_FOUND
Не удается разрешить по крайней мере одного получателя в параметре lpAdrList . Обычно это значение возвращается при установке флага MAPI_DIALOG, запрещающего отображение диалогового окна.
Замечания
Клиенты и поставщики услуг вызывают метод ResolveName , чтобы инициировать процесс разрешения имен. Неразрешенная запись — это запись, которая еще не имеет идентификатора записи или свойства PR_ENTRYID (PidTagEntryId).
ResolveName проходит следующий процесс для каждой неразрешенной записи в списке адресов, переданной в параметре lpAdrList .
Если тип адреса получателя соответствует формату SMTP-адреса ( displayname@ domain.top-level-domain), ResolveName назначает ему одноразовый идентификатор записи.
Для каждого контейнера в свойстве PR_AB_SEARCH_PATH (PidTagAbSearchPath) ResolveName вызывает метод IABContainer::ResolveNames . ResolveNames пытается сопоставить отображаемое имя каждого неразрешенного получателя с отображаемым именем, принадлежащим одной из его записей.
Если контейнер не поддерживает ResolveNames, ResolveName ограничивает таблицу содержимого контейнера с помощью ограничения свойств PR_ANR (PidTagAnr). Это ограничение приводит к тому, что контейнер выполняет поиск по типу "лучше всего угадывается", чтобы найти соответствующего получателя. Все контейнеры должны поддерживать ограничение свойства PR_ANR .
Когда контейнер возвращает получателя, соответствующего нескольким именам, resolveName отображает диалоговое окно, если установлен флаг MAPI_DIALOG, что позволяет пользователю выбрать правильное имя.
Если все контейнеры в свойстве PR_AB_SEARCH_PATH были вызваны и совпадения не найдены, получатель остается неразрешенным.
Если один или несколько получателей не разрешены, ResolveName возвращает MAPI_E_NOT_FOUND. Если у одного или нескольких получателей было неоднозначное разрешение, которое не удалось разрешить с помощью диалогового окна, или если флаг MAPI_DIALOG не задан, ResolveName возвращает MAPI_E_AMBIGUOUS_RECIP. Если некоторые из получателей неоднозначны, а некоторые не могут быть разрешены, ResolveName может вернуть любое значение ошибки.
Если не удается разрешить имя, клиент может создать одноразовый адрес со специально отформатированным адресом и идентификатором записи. Дополнительные сведения о формате однократных входных идентификаторов см. в разделе Идентификаторы однократных входов. Дополнительные сведения о формате одноразовых адресов см. в разделе Одноразовые адреса.
MAPI поддерживает символьные строки Юникода для ADRLIST и новые параметры заголовка записи в ResolveName; Если задать флаг MAPI_UNICODE, в структурах ADRENTRY возвращаются следующие свойства в качестве типа PT_UNICODE:
PR_ADDRTYPE (PidTagAddressType)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_EMAIL_ADDRESS (PidTagEmailAddress)
PR_TRANSMITABLE_DISPLAY_NAME (PidTagTransmittableDisplayName)
Однако свойство PR_7BIT_DISPLAY_NAME (PidTag7BitDisplayName) всегда возвращается как тип PT_STRING8.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | ����������� |
|---|---|---|
| MAPIABFunctions.cpp |
AddOneOffAddress |
MFCMAPI использует метод ResolveName для разрешения однократного адреса перед добавлением его в сообщение. |
| MAPIABFunctions.cpp |
AddRecipient |
MFCMAPI использует метод ResolveName для поиска записи адресной книги по отображаемого имени. |