IMAPISession::QueryIdentity

Статья
04/04/2023

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

Возвращает идентификатор записи объекта, который предоставляет первичное удостоверение для сеанса.

HRESULT QueryIdentity(
  ULONG FAR * lpcbEntryID,
  LPENTRYID FAR * lppEntryID
);

Параметры

lpcbEntryID

[out] Указатель на число байтов в идентификаторе записи, на который указывает параметр lppEntryID .

lppEntryID

[out] Указатель на указатель на идентификатор входа объекта, предоставляющего первичное удостоверение.

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

S_OK

Основное удостоверение было успешно возвращено.

MAPI_W_NO_SERVICE

Вызов выполнен успешно, но основное удостоверение для сеанса отсутствует. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . Дополнительные сведения см. в разделе Использование макросов для обработки ошибок.

Замечания

Метод IMAPISession::QueryIdentity извлекает первичное удостоверение для текущего сеанса и возвращает значение через параметр lppEntryID . Основное удостоверение — это объект , обычно пользователь обмена сообщениями, представляющий пользователя сеанса. lppEntryID возвращает первичное удостоверение для объекта IMailUser , которое также хранится в качестве свойства PidTagEntryID . Значение, возвращаемое в lppEntryID , можно использовать для открытия объекта IMailUser с помощью IMAPISession::OpenEntry.

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

Флаг STATUS_PRIMARY_IDENTITY в свойстве PR_RESOURCE_FLAGS (PidTagResourceFlags).
Свойство PR_IDENTITY_DISPLAY (PidTagIdentityDisplay).
Свойство PR_IDENTITY_ENTRYID (PidTagIdentityEntryId).
Свойство PR_IDENTITY_SEARCH_KEY (PidTagIdentitySearchKey).

Если поставщик услуг, предоставляющий основное удостоверение, принадлежит службе сообщений, другие поставщики служб в службе сообщений также задают свойства PR_IDENTITY. Эти свойства публикуются в таблице состояния сеанса.

По возможности QueryIdentity возвращает значение свойства PR_IDENTITY_ENTRYID из строки состояния, помеченной STATUS_PRIMARY_IDENTITY. Если свойство PR_IDENTITY_ENTRYID отсутствует в основной строке удостоверения, QueryIdentity возвращает одноразовый идентификатор записи, созданный с другими сведениями из этой строки.

Если флаг STATUS_PRIMARY_IDENTITY отсутствует во всех столбцах PR_RESOURCE_FLAG в таблице состояния, QueryIdentity возвращает первый идентификатор записи, который он находит. Если нет соответствующего идентификатора записи для возврата, QueryIdentity завершается с предупреждением MAPI_W_NO_SERVICE и указывает lppEntryID на жестко закодированный идентификатор записи.

Примечания для вызывающих методов

Можно вызвать метод IMsgServiceAdmin::SetPrimaryIdentity , чтобы назначить службе сообщений задачу предоставления основного удостоверения сеанса.

Другой способ получения первичного удостоверения — поиск в таблице состояния строки с PR_RESOURCE_FLAGS столбцами, для которого задано значение STATUS_PRIMARY_IDENTITY. Дополнительные сведения об этом альтернативном способе получения сведений об удостоверениях см. в разделе Таблица состояния и объекты состояния.

По завершении использования идентификатора записи для основного удостоверения, возвращенного QueryIdentity, освободите его память, вызвав функцию MAPIFreeBuffer .

Дополнительные сведения об удостоверении в целом см. в разделе Основное удостоверение MAPI.

Дополнительные сведения о получении удостоверения сеанса MAPI см. в разделе Извлечение удостоверений основного и поставщика.

Справочные материалы по MFCMAPI

Пример кода MFCMAPI указан в приведенной ниже таблице.

Файл	Функция	Comment
MainDlg.cpp	CMainDlg::OnQueryIdentity	MFCMAPI использует метод IMAPISession::QueryIdentity для открытия записи адресной книги для основного удостоверения сеанса.