MAPILogonEx
Область применения: Outlook 2013 | Outlook 2016
Регистрирует клиентское приложение в сеансе с помощью системы обмена сообщениями.
| Свойство | Значение |
|---|---|
| Файл заголовка: |
Mapix.h |
| Реализовано в: |
MAPI |
| Вызывающая сторона: |
Клиентские приложения |
HRESULT MAPILogonEx(
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
LPSTR lpszPassword,
FLAGS flFlags,
LPMAPISESSION FAR * lppSession
);
Параметры
ulUIParam
[в] Дескриптор к окну, в котором диалоговое окно входа является модальным. Если диалоговое окно не отображается во время вызова, параметр ulUIParam игнорируется. Этот параметр может быть равен нулю.
lpszProfileName
[в] Указатель на строку, содержащую имя профиля, используемого при входе пользователя. Эта строка ограничена 64 символами.
lpszPassword
[в] Указатель на строку, содержащую пароль профиля. Параметр lpszPassword должен иметь значение NULL.
flFlags
[в] Битовая маска флагов, используемая для управления способом входа. Можно задать следующие флаги:
MAPI_ALLOW_OTHERS
Должен быть возвращен общий сеанс, что позволяет последующим клиентам получать сеанс без предоставления учетных данных пользователя.
MAPI_APP_PROFILE
Включите профили приложений в список диалоговых окон входа. Если этот флаг не задан, профили приложений не включаются. Этот флаг не распознается или поддерживается во всех реализациях MAPI.
MAPI_BG_SESSION
Войдите в сеанс и выполните все операции в фоновом режиме. Как правило, если клиент намерен выполнять обработку в фоновом потоке или отдельным процессом, ненавязчивым для потока переднего плана, он должен вызывать с флагом MAPI_BG_SESSION. Примерами использования MAPI_BG_SESSION является клиентское приложение, например подсистема индексирования или открытие файла личных папок (PST) для доступа к фоновому типу. MAPILogonEx.
MAPI_EXPLICIT_PROFILE
Не следует использовать профиль по умолчанию, и пользователь должен предоставить профиль.
MAPI_EXTENDED
Войдите в систему с расширенными возможностями. Этот флаг всегда должен быть установлен.
MAPI_FORCE_DOWNLOAD
Перед возвратом необходимо скачать все сообщения пользователя. Если флаг MAPI_FORCE_DOWNLOAD не задан, сообщения можно скачать в фоновом режиме после возврата вызова MAPILogonEx.
MAPI_LOGON_UI
Должно появиться диалоговое окно с запросом у пользователя ввести сведения о входе при необходимости. Если флаг MAPI_LOGON_UI не задан, вызывающий клиент не отображает диалоговое окно входа и возвращает значение ошибки, если пользователь не вошел в систему.
MAPI_NEW_SESSION
Следует предпринять попытку создать новый сеанс MAPI вместо получения общего сеанса. Если флаг MAPI_NEW_SESSION не задан, MAPILogonEx использует существующий общий сеанс, даже если параметр lpszprofileName не имеет значения NULL.
MAPI_NO_MAIL
MAPI не должен сообщать диспетчеру очереди MAPI о существовании сеанса. В результате никакие сообщения не могут быть отправлены или получены в сеансе, кроме как через тесно связанную пару хранилища и транспорта. Вызывающий клиент устанавливает этот флаг, если он выступает в качестве агента, если необходимо выполнить работу по настройке или если клиент просматривает доступные хранилища сообщений.
MAPI_NT_SERVICE
Вызывающий объект работает как служба Windows. Вызывающие пользователи, которые не работают как служба Windows, не должны устанавливать этот флаг; Вызывающие пользователи, работающие как служба, должны установить этот флаг.
MAPI_SERVICE_UI_ALWAYS
MAPILogonEx должно отображать диалоговое окно конфигурации для каждой службы сообщений в профиле. Диалоговые окна отображаются после выбора профиля, но до входа в службу сообщений. Общее диалоговое окно MAPI для входа также содержит поле проверка, которое запрашивает ту же операцию.
MAPI_TIMEOUT_SHORT
Вход должен завершиться ошибкой, если он заблокирован более чем на несколько секунд.
MAPI_UNICODE
Переданные строки имеют формат Юникода. Если флаг MAPI_UNICODE не задан, строки имеют формат ANSI.
MAPI_USE_DEFAULT
Подсистема обмена сообщениями должна заменить имя профиля по умолчанию для параметра lpszProfileName . Флаг MAPI_EXPLICIT_PROFILE игнорируется, если lpszProfileName не имеет значение NULL или пусто.
lppSession
[out] Указатель на указатель на интерфейс сеанса MAPI.
Возвращаемое значение
S_OK
Вход выполнен успешно.
MAPI_E_LOGON_FAILED
Вход не удалось выполнить либо из-за того, что один или несколько параметров MAPILogonEx были недопустимыми, либо из-за того, что было открыто слишком много сеансов.
MAPI_E_TIMEOUT
MAPI сериализует все входы через мьютекс. Возвращается, если был установлен флаг MAPI_TIMEOUT_SHORT, а другой поток содержал мьютекс.
MAPI_E_USER_CANCEL
Пользователь отменил операцию, обычно нажав кнопку Отмена в диалоговом окне.
Замечания
Клиентские приложения MAPI вызывают функцию MAPILogonEx для входа в сеанс с помощью системы обмена сообщениями. Все строки, которые передаются и возвращаются в вызовы MAPI и из них, заканчиваются значением NULL и должны быть указаны в текущем наборе символов или кодовой странице вызывающего клиента или поставщика операционной системы.
Параметр lpszProfileName игнорируется, если существует предыдущий сеанс с именем MapiLogonEx с установленным флагом MAPI_ALLOW_OTHERS и если MAPI_NEW_SESSION флага не задан. Если параметр lpszProfileName имеет значение NULL или указывает на пустую строку, а параметр flFlags включает флаг MAPI_LOGON_UI, функция MAPILogonEx создает диалоговое окно входа с пустым полем для имени профиля.
При входе в определенный профиль клиент должен передать флаг MAPI_NEW_SESSION в MAPILogonEx в дополнение к имени профиля. В противном случае, если другой клиент установил общий сеанс, выполнив вход с помощью MAPI_ALLOW_OTHERS, клиент будет входить в общий сеанс, а не в запрошенный профиль.
Флаг MAPI_EXPLICIT_PROFILE не приводит к использованию имени профиля по умолчанию, если lpszProfileName имеет значение NULL или пусто, если флаг MAPI_USE_DEFAULT также не присутствует.
Флаг MAPI_NO_MAIL имеет несколько эффектов, которые приводят к следующим последствиям, если не используется диспетчер очереди MAPI:
Во время этого сеанса диспетчер очереди MAPI не может отправлять или доставлять сообщения. Отправлять и доставлять сообщения могут только тесно связанные поставщики магазинов и транспортных услуг.
Серверные хранилища по-прежнему могут отправлять или доставлять сообщения.
Сообщения, отправленные или доставляемые серверными хранилищами, не обрабатываются никакими поставщиками перехватчиков.
Параметры транспорта для каждого сообщения и получателя недоступны.
Таблица состояния не содержит записей для поставщиков транспорта, а любые функции транспорта, зависящие от объектов состояния (например, конфигурации), недоступны.
Строка очереди сообщений в таблице состояния содержит значение STATUS_FAILURE.
Вход с пиггибэкатом разрешен, но эти входы не приводят к тому, что предыдущий вход будет получать обновления объекта состояния.
Служба всегда должна входить в систему с помощью флага MAPI_NO_MAIL.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| MAPIObjects.cpp |
CMapiObjects::MAPILogonEx |
MFCMAPI использует метод MAPILogonEx для входа в MAPI. |