IABProvider::Logon
Область применения: Outlook 2013 | Outlook 2016
Устанавливает подключение к активному сеансу.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
Параметры
lpMAPISup
[в] Указатель на объект поддержки поставщика адресной книги.
ulUIParam
[в] Дескриптор родительского окна для диалогового окна входа, отображаемого методом Logon , если это разрешено. Параметр ulUIParam содержит значение параметра с тем же именем, которое передается в MAPI при предыдущем вызове функции MAPILogonEx .
lpszProfileName
[в] Указатель на имя профиля сеанса.
ulFlags
[в] Битовая маска флагов, управляющая тем, как выполняется вход. Можно задать следующие флаги:
AB_NO_DIALOG
Поставщик не должен отображать диалоговое окно во время входа. Если этот флаг не установлен, поставщик может отобразить диалоговое окно с запросом у пользователя отсутствующих сведений о конфигурации.
MAPI_DEFERRED_ERRORS
Позволяет успешно вернуть вход , возможно, до завершения процесса входа.
MAPI_UNICODE
Все строки должны быть в формате Юникода. Если флаг MAPI_UNICODE не задан, строки должны иметь формат ANSI.
lpulcbSecurity
[вход, выход] Указатель на размер (в байтах) структуры учетных данных безопасности, на которую указывает параметр lppbSecurity . На входных данных значение должно быть ненулевым; в выходных данных значение должно быть равным нулю. В обоих случаях указатели должны быть допустимыми.
lppbSecurity
[вход, выход] Указатель на указатель на учетные данные безопасности. На входных данных значение должно быть ненулевым; в выходных данных значение должно быть равным нулю. В обоих случаях указатель должен быть допустимым.
lppMAPIError
[out] Указатель на указатель на структуру MAPIERROR . Параметру lppMAPIError можно задать значение NULL, если нет возвращаемой структуры MAPIERROR.
lppABLogon
[out] Указатель на указатель на объект входа поставщика.
Возвращаемое значение
S_OK
Подключение к активному сеансу успешно установлено.
MAPI_E_FAILONEPROVIDER
Поставщик не может войти в систему, но MAPI может продолжать вход в другие поставщики в службе сообщений, к которой принадлежит поставщик.
MAPI_E_UNCONFIGURED
У поставщика недостаточно сведений для завершения входа. MAPI вызывает функцию входа в службу сообщений поставщика.
MAPI_E_UNKNOWN_CPID
Сервер не настроен для поддержки кодовой страницы клиента.
MAPI_E_UNKNOWN_LCID
Сервер не настроен для поддержки сведений о языковом стандарте клиента.
MAPI_E_USER_CANCEL
Пользователь отменил операцию, обычно нажав кнопку Отмена в диалоговом окне входа.
Замечания
Connections устанавливаются с каждым поставщиком адресной книги в профиле сеанса, когда клиент вызывает метод IMAPISession::OpenAddressBook. Затем OpenAddressBook вызывает метод Logon каждого поставщика.
Имя профиля, на которое указывает параметр lpszProfileName , отображается в наборе символов клиента пользователя, на что указывает наличие или отсутствие флага MAPI_UNICODE в параметре ulFlags .
Примечания для исполнителей
В реализации метода Logon вызовите метод IMAPISupport::SetProviderUID , чтобы зарегистрировать уникальный идентификатор или структуру MAPIUID . Каждый из объектов будет иметь идентификатор записи, который включает этот MAPIUID. MAPI использует MAPIUID для сопоставления объекта с его поставщиком. Например, когда клиент вызывает метод IMAPISession::OpenEntry для открытия пользователя обмена сообщениями, OpenEntry проверяет часть mapIUID переданного идентификатора записи и сопоставляет ее с MAPIUID , зарегистрированным поставщиком адресной книги.
Если клиент входит в систему поставщика несколько раз, может потребоваться зарегистрировать другой MAPIUID для каждого входа. Регистрация уникальных структур MAPIUID позволяет MAPI правильно направлять запросы к соответствующему экземпляру поставщика. Однако может потребоваться, чтобы каждый объект входа совместно предоставил один MAPIUID. В этом случае вы должны иметь возможность самостоятельно обрабатывать маршрутизацию, а не полагаться на MAPI. Дополнительные сведения о создании MAPIUID см. в разделе Регистрация уникальных идентификаторов поставщика услуг.
Объект поддержки, который MAPI передает методу Logon в параметре lpMAPISup , предоставляет доступ ко многим методам, включенным в интерфейс IMAPISupport: IUnknown . MAPI создает объект поддержки, настроенный для вашего типа поставщика. Например, если вам нужно войти в базовую систему обмена сообщениями или службу каталогов при установке подключения, можно вызвать метод IMAPISupport::OpenProfileSection , чтобы получить учетные данные безопасности для этого конкретного сеанса входа.
Если вход выполнен успешно, убедитесь, что вы вызываете метод IUnknown::AddRef объекта поддержки для увеличения числа ссылок. Это позволяет поставщику удерживать указатель объекта поддержки до конца сеанса. Если не вызвать этот метод AddRef , MAPI выгрузит поставщик.
Имя профиля, переданное в параметр lpszProfileName , можно включить в диалоговые окна ошибок, экраны входа или другие пользовательские интерфейсы. Чтобы использовать имя профиля, скопируйте его в выделенное хранилище.
Создайте объект входа и верните на него указатель в параметре lppABLogon . MAPI использует этот объект входа для вызова методов в реализации IABLogon .
Если во время входа требуется пароль, отображайте диалоговое окно входа только в том случае, если флаг AB_NO_DIALOG не задан. Если пользователь отменяет процесс входа, обычно нажимая кнопку Отмена в диалоговом окне, верните MAPI_E_USER_CANCEL из параметра Вход.
Как правило, если поставщику адресной книги не удается войти в систему, MAPI отключает службу сообщений, к которой принадлежит поставщик, к которому принадлежит сбой, то есть MAPI не будет пытаться установить подключения для других поставщиков, принадлежащих службе до конца времени существования сеанса. Однако если поставщику не удается установить подключение и вы не хотите отключать всю службу, верните MAPI_E_FAILONEPROVIDER или MAPI_E_UNCONFIGURED. MAPI не отключает службу сообщений, к которой принадлежит поставщик.
Верните MAPI_E_FAILONEPROVIDER, если возникает ошибка, которая не является достаточно серьезной, чтобы другие поставщики в службе сообщений не устанавливали подключения. Верните MAPI_E_UNCONFIGURED, если необходимые сведения о конфигурации отсутствуют в профиле и вы не можете отобразить диалоговое окно с запросом пользователя. MAPI будет отвечать, вызывая функцию точки входа службы сообщений поставщика с MSG_SERVICE_CONFIGURE задан в качестве параметра ulContext , чтобы предоставить службе возможность настроить себя либо программным способом, либо с помощью листа свойств. После завершения функции точки входа службы сообщений MAPI повторяет вход.