IXPProvider::TransportLogon
Область применения: Outlook 2013 | Outlook 2016
Устанавливает сеанс, в котором клиентское приложение выполняет вход в поставщик транспорта.
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
Параметры
lpMAPISup: [in] Указатель на объект поддержки поставщика транспорта для функций обратного вызова в MAPI для этого сеанса. Этот объект остается действительным до тех пор, пока поставщик транспорта не отпустит его.
ulUIParam: [in] Обработайте родительское окно диалоговых окон или окон, отображаемых этим методом. Параметр ulUIParam может быть не равен NULL, например, если флаг LOGON_SETUP задан в параметре lpulFlags .
lpszProfileName: [in] Указатель на имя профиля пользователя. Параметр lpszProfileName в основном используется при представлении диалогового окна.
lpulFlags: [in, out] Bitmask флагов, которые управляют способом установки сеанса входа. Для ввода с помощью диспетчера очереди MAPI можно задать следующие флаги:
LOGON_NO_CONNECT: учетная запись пользователя входит в этот поставщик транспорта для целей, отличных от передачи и получения сообщений. Поставщик транспорта не должен пытаться установить какие-либо подключения к другим системам обмена сообщениями.
LOGON_NO_DIALOG. Диалоговое окно не должно отображаться, даже если сохраненные учетные данные пользователя недопустимы или недостаточны для входа.
LOGON_NO_INBOUND. Поставщику транспорта не нужно инициализировать для получения сообщений и не принимать входящие сообщения. Диспетчер очереди MAPI может использовать метод IXPLogon::TransportNotify позже, чтобы сообщить поставщику транспорта о включении обработки входящих сообщений.
LOGON_NO_OUTBOUND: поставщику транспорта не требуется инициализировать для отправки сообщений, так как диспетчер очереди MAPI не предоставляет их. Если клиентскому приложению требуется подключение к удаленному поставщику во время составления сообщения, чтобы оно ему можно было выполнять вызовы метода IXPLogon::AddressTypes , поставщик транспорта должен установить подключение. Диспетчер очереди MAPI может использовать TransportNotify , чтобы сообщить поставщику транспорта о начале исходящих операций.
MAPI_UNICODE: переданная строка для имени профиля имеет формат Юникода. Если флаг MAPI_UNICODE не задан, строка имеет формат ANSI.
Поставщик транспорта может задать следующие флаги для выходных данных:
LOGON_SP_IDLE: запрашивает, чтобы диспетчер очереди MAPI часто вызывал метод IXPLogon::Idle поставщика транспорта для обработки во время простоя.
LOGON_SP_POLL: запрашивает, чтобы диспетчер очереди MAPI часто вызывал метод IXPLogon::P oll для возвращаемого объекта входа, чтобы проверка для новых сообщений. Если этот флаг не задан, диспетчер очереди MAPI проверяет наличие новых сообщений только в том случае, если поставщик транспорта использует метод IMAPISupport::SpoolerNotify для уведомления диспетчера очереди о наличии новых сообщений для обработки. Поставщик транспорта фактически становится только для отправки, не устанавливая этот флаг и не уведомляя диспетчер очереди MAPI о получении сообщения.
LOGON_SP_RESOLVE. Запросы, разрешаемые диспетчером очереди MAPI, на полный адрес всех адресов сообщений для получателей, не поддерживаемых этим поставщиком транспорта. Таким образом, поставщик транспорта может создать путь ответа для всех получателей.
MAPI_UNICODE. Возвращаемые строки в структуре MAPIERROR , если таковые имеются, имеют формат Юникода. Если флаг MAPI_UNICODE не задан, строки имеют формат ANSI.
lppMAPIError: [out] Указатель на указатель на возвращенную структуру MAPIERROR , если она есть, которая содержит сведения о версии, компоненте и контексте для ошибки. Параметру lppMAPIError можно задать значение NULL, если нет возвращаемой структуры MAPIERROR.
lppXPLogon: [out] Указатель на указатель на возвращенный объект входа поставщика транспорта.
Возвращаемое значение
S_OK: вызов выполнен успешно и вернул ожидаемое значение или значения.
MAPI_E_FAILONEPROVIDER. Этот поставщик не может войти в систему, но эта ошибка не должна отключать службу.
MAPI_E_UNCONFIGURED. Профиль не содержит достаточно сведений для завершения входа. MAPI вызывает функцию точки входа службы сообщений поставщика.
MAPI_E_UNKNOWN_CPID: поставщик не может поддерживать кодовую страницу клиента.
MAPI_E_UNKNOWN_LCID. Поставщик не может поддерживать сведения о языковом стандарте клиента.
MAPI_E_USER_CANCEL. Пользователь отменил операцию, обычно нажав кнопку Отмена в диалоговом окне.
Замечания
Диспетчер очереди MAPI вызывает метод IXPProvider::TransportLogon , чтобы установить сеанс входа для пользователя.
Большинство поставщиков транспорта используют метод IMAPISupport::OpenProfileSection , предоставленный объектом поддержки, на который указывает параметр lpMAPISup , для сохранения и получения сведений об удостоверениях пользователя, адресов серверов и учетных данных. С помощью OpenProfileSection поставщик транспорта может сохранить произвольные сведения и связать их с входом в конкретный ресурс. Например, поставщик может использовать OpenProfileSection для сохранения имени учетной записи и пароля, связанных с определенным сеансом, а также любых имен серверов или других необходимых сведений, необходимых для доступа к ресурсам для этого сеанса. MAPI скрывает информацию, связанную с ресурсом, из внешнего доступа. Раздел профиля, доступный через lpMAPISup , управляется диспетчером очереди MAPI, поэтому данные, связанные с этим контекстом пользователя, отделяются от данных для других контекстов.
Поставщик транспорта должен вызвать метод IUnknown::AddRef для объекта поддержки и сохранить копию указателя на этот объект как часть объекта входа поставщика.
Отображаемое имя профиля в lpszProfileName предоставляется, чтобы поставщик транспорта смог использовать его в сообщениях об ошибках или диалоговых окнах входа. Если поставщик сохраняет это имя, оно должно быть скопировано в хранилище, выделенное поставщиком.
Поставщикам транспорта, которые тесно связаны с другими поставщиками услуг, может потребоваться выполнить дополнительную работу при входе в систему, чтобы установить хорошие учетные данные, необходимые для операций между поставщиками-компаньонами.
Обычно поставщики транспорта открываются при первом входе пользователя в профиль. Так как первый вход в профиль обычно выполняется перед входом в любое хранилище сообщений, диспетчер очереди MAPI обычно вызывает TransportLogon с флагами LOGON_NO_INBOUND и LOGON_NO_OUTBOUND, установленными в lpulFlags. Позже, когда соответствующие хранилища сообщений будут доступны в сеансе профиля, диспетчер очереди MAPI вызывает TransportNotify , чтобы инициировать входящие и исходящие операции для поставщика транспорта.
Передача флага LOGON_NO_CONNECT в lpulFlags сигнализирует об автономной работе поставщика транспорта. Этот флаг указывает, что внешние подключения не должны быть выполнены; Если поставщик транспорта не может установить сеанс без внешнего подключения, он должен вернуть значение ошибки для входа.
Поставщик транспорта должен задать флаг LOGON_SP_IDLE в lpulFlags во время инициализации, если он предназначен для использования времени, которое система в противном случае тратит на простой. Такое время часто используется для обработки автоматических операций, таких как автоматическая загрузка сообщений, скачивание сообщений по времени или отправка сообщений по времени. Если этот флаг установлен, средство spooler MAPI вызывает бездействия , когда наступает время простоя системы для запуска таких операций. Диспетчер очереди MAPI не вызывает простой через заданные интервалы; вместо этого он вызывается только во время реального простоя. Таким образом, поставщики не должны исходить из предположения о том, как часто будут вызываться их методы простоя . Поставщики, поддерживающие операции бездействия, должны предоставить для него пользовательский интерфейс конфигурации на странице свойств поставщика.
Если вход поставщика транспорта выполнен успешно, поставщик должен вернуть в параметре lppXPLogon указатель на объект входа. Диспетчер очереди MAPI будет использовать этот объект для дополнительного доступа к поставщику. Если transportLogon отображает диалоговое окно входа и пользователь обычно отменяет вход, нажимая кнопку Отмена в диалоговом окне, поставщик должен вернуть MAPI_E_USER_CANCEL.
Для большинства значений ошибок, возвращаемых из TransportLogon, MAPI отключает службы сообщений, к которым принадлежит поставщик. MAPI не будет вызывать поставщиков, принадлежащих этой службе, в течение оставшейся части сеанса MAPI. В отличие от этого, когда TransportLogon возвращает значение ошибки MAPI_E_FAILONEPROVIDER из входа, MAPI не отключает службу сообщений, к которой принадлежит поставщик. TransportLogon должен возвращать MAPI_E_FAILONEPROVIDER, если возникает ошибка, не требующая отключения службы на оставшуюся часть сеанса.
Если поставщик возвращает MAPI_E_UNCONFIGURED из входа, MAPI вызовет функцию входа в службу сообщений поставщика, а затем повторите вход. MAPI передает MSG_SERVICE_CONFIGURE в качестве контекста, чтобы предоставить службе возможность настроить себя. Если клиент решил разрешить пользовательский интерфейс при входе в систему, служба может представить свой лист свойств конфигурации, чтобы пользователь смог ввести сведения о конфигурации.
Если поставщик обнаружит, что все необходимые сведения отсутствуют в профиле, он должен вернуть MAPI_E_UNCONFIGURED, чтобы MAPI вызовет функцию точки входа службы сообщений поставщика.