IMSProvider::Logon
Область применения: Outlook 2013 | Outlook 2016
Регистрирует MAPI в одном экземпляре поставщика хранилища сообщений.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags,
LPCIID lpInterface,
ULONG FAR * lpcbSpoolSecurity,
LPBYTE FAR * lppbSpoolSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPMSLOGON FAR * lppMSLogon,
LPMDB FAR * lppMDB
);
Параметры
lpMAPISup
[в] Указатель на текущий объект поддержки MAPI для хранилища сообщений.
ulUIParam
[в] Дескриптор родительского окна любых диалоговых окон или окон, отображаемых этим методом.
lpszProfileName
[в] Указатель на строку, содержащую имя профиля, используемого для входа поставщика хранилища. Эта строка может отображаться в диалоговых окнах, записываться в файл журнала или просто игнорироваться. Если флаг MAPI_UNICODE установлен в параметре ulFlags , он должен быть в формате Юникода.
cbEntryID
[в] Размер (в байтах) идентификатора записи, на который указывает параметр lpEntryID .
lpEntryID
[в] Указатель на идентификатор записи для хранилища сообщений. Передача null в lpEntryID означает, что хранилище сообщений еще не выбрано и что могут отображаться диалоговые окна, позволяющие пользователю выбрать хранилище сообщений.
ulFlags
[в] Битовая маска флагов, управляющая тем, как выполняется вход. Можно задать следующие флаги:
MAPI_DEFERRED_ERRORS
Вызов может завершиться успешно, даже если базовый объект недоступен для реализации вызова. Если объект недоступен, последующий вызов объекта может вызвать ошибку.
MAPI_UNICODE
Переданные строки имеют формат Юникода. Если MAPI_UNICODE не задано, строки имеют формат ANSI.
MDB_NO_DIALOG
Запрещает отображение диалоговых окон входа. Если этот флаг установлен, в случае неудачного входа возвращается значение ошибки MAPI_E_LOGON_FAILED. Если этот флаг не установлен, поставщик хранилища сообщений может предложить пользователю исправить имя или пароль, вставить диск или выполнить другие действия, необходимые для подключения к хранилищу.
MDB_NO_MAIL
Хранилище сообщений не должно использоваться для отправки или получения почты. Флаг указывает MAPI не уведомлять диспетчер очереди MAPI о том, что это хранилище сообщений открыто. Если этот флаг установлен и хранилище сообщений тесно связано с поставщиком транспорта, поставщику не нужно вызывать метод IMAPISupport::SpoolerNotify .
MDB_TEMPORARY
Журналы в хранилище, чтобы данные можно было получить программными средствами из раздела профиля без использования диалоговых окон. Этот флаг указывает MAPI, что хранилище не должно быть добавлено в таблицу хранилища сообщений и что хранилище не может быть постоянным. Если этот флаг установлен, поставщикам хранилища сообщений не нужно вызывать метод IMAPISupport::ModifyProfile .
MDB_WRITE
Запрашивает разрешение на чтение и запись.
lpInterface
[в] Указатель на идентификатор интерфейса (IID) для хранилища сообщений для входа. Передача значения NULL указывает, что возвращается интерфейс MAPI для хранилища сообщений ( IMsgStore). Параметру lpInterface также можно задать идентификатор соответствующего интерфейса для хранилища сообщений (например, IID_IUnknown или IID_IMAPIProp).
lpcbSpoolSecurity
[out] Указатель на переменную, в которой поставщик хранилища возвращает размер (в байтах) данных проверки в параметре lppbSpoolSecurity .
lppbSpoolSecurity
[out] Указатель на указатель на возвращенные данные проверки. Эти данные проверки предоставляются, поэтому метод IMSProvider::SpoolerLogon может записать диспетчер очереди MAPI в то же хранилище, что и поставщик хранилища сообщений.
lppMAPIError
[out] Указатель на указатель на возвращенную структуру MAPIERROR , если она имеется, которая содержит сведения о версии, компоненте и контексте для ошибки. Параметру lppMAPIError может быть присвоено значение NULL, если нет возвращаемой структуры MAPIERROR.
lppMSLogon
[out] Указатель на указатель на объект входа в хранилище сообщений для входа в MAPI.
lppMDB
[out] Указатель на указатель на объект хранилища сообщений для диспетчера очереди MAPI и клиентских приложений для входа.
Возвращаемое значение
S_OK
����� ������� � ������ ��������� ��������� ��� ��������.
MAPI_E_FAILONEPROVIDER
Этот поставщик не может войти в систему, но эта ошибка не должна отключать службу.
MAPI_E_LOGON_FAILED
Не удалось установить сеанс входа.
MAPI_E_UNCONFIGURED
Профиль не содержит достаточно сведений для завершения входа. При возврате этого значения MAPI вызывает функцию точки входа службы сообщений поставщика хранилища сообщений.
MAPI_E_USER_CANCEL
Пользователь отменил операцию, обычно нажав кнопку Отмена в диалоговом окне.
MAPI_E_UNKNOWN_CPID
Сервер не настроен для поддержки кодовой страницы клиента.
MAPI_E_UNKNOWN_LCID
Сервер не настроен для поддержки сведений о языковом стандарте клиента.
MAPI_W_ERRORS_RETURNED
Вызов выполнен успешно, но у поставщика хранилища сообщений доступны сведения об ошибках. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . Дополнительные сведения см. в разделе Использование макросов для обработки ошибок. Чтобы получить сведения об ошибке от поставщика, вызовите метод IMAPISession::GetLastError .
Замечания
MAPI вызывает метод IMSProvider::Logon для выполнения большей части обработки, необходимой для получения доступа к хранилищу сообщений. Поставщики хранилища сообщений проверяют все учетные данные пользователя, необходимые для доступа к определенному хранилищу, и возвращают объект хранилища сообщений в параметре lppMDB , в который может войти диспетчер spooler MAPI и клиентские приложения.
Помимо возвращенного объекта хранилища сообщений, используемого клиентом и диспетчером очереди MAPI, поставщик также возвращает объект входа в хранилище сообщений для MAPI, который будет использоваться при управлении открытым хранилищем. Объект входа в хранилище сообщений и объект хранилища сообщений должны быть тесно связаны внутри поставщика хранилища сообщений, чтобы каждая из них могла влиять на другую. Использование объекта store и объекта входа должно быть идентичным; между объектом входа и объектом store должно быть одно к одному соответствие, чтобы объекты действовали так, как будто они являются одним объектом, предоставляющим два интерфейса. Эти два объекта также должны быть созданы вместе и освобождены вместе.
Объект поддержки MAPI, созданный MAPI и переданный поставщику в параметре lpMAPISup , предоставляет доступ к функциям в MAPI, которые требуются поставщику. К ним относятся функции, которые сохраняют и извлекают сведения о профилях, обращаются к адресным книгам и т. д. Указатель lpMAPISup может отличаться для каждого открываемого хранилища. При обработке вызовов для хранилища сообщений после входа поставщик хранилища должен использовать переменную lpMAPISup , относяющуюся к конкретному хранилищу. Для любого вызова входа , который открывает хранилище сообщений и успешно создает объект входа в хранилище сообщений, поставщик должен сохранить указатель на объект поддержки MAPI в объекте входа в store и вызвать метод IUnknown::AddRef , чтобы добавить ссылку на объект поддержки.
Параметр ulUIParam следует использовать, если поставщик предоставляет диалоговые окна во время вызова входа . Однако диалоговые окна не должны отображаться, если ulFlags содержит флаг MDB_NO_DIALOG. Если необходимо вызвать пользовательский интерфейс, но ulFlags не разрешает его, или если по какой-либо другой причине не удается отобразить пользовательский интерфейс, поставщик должен вернуть MAPI_E_LOGON_FAILED. Если при входе отображается диалоговое окно и пользователь отменяет вход(обычно нажимая кнопку Отмена ) диалогового окна, поставщик должен вернуть MAPI_E_USER_CANCEL.
Параметр lpEntryID может иметь значение NULL или указывать на идентификатор записи незавершенного хранилища, созданный ранее. Если lpEntryID указывает на идентификатор незавершенной записи, этот идентификатор записи может поступать из одного из нескольких мест:
Это может быть идентификатор записи, который поставщик хранилища ранее упаковал и записал в раздел профиля в качестве свойства PR_ENTRYID (PidTagEntryId).
Это может быть идентификатор записи, который поставщик ранее упаковал и вернул вызывающему клиенту в качестве свойства PR_STORE_ENTRYID (PidTagStoreEntryId).
Это может быть идентификатор записи, который поставщик ранее упаковал и вернул вызывающему клиенту в качестве свойства PR_ENTRYID объекта хранилища сообщений.
В любом из этих случаев возможно, что идентификатор записи был создан на компьютере, отличном от используемого в настоящее время.
Если lpEntryID не имеет значения NULL, он должен содержать все сведения, необходимые для идентификации и поиска хранилища сообщений. Эти сведения могут включать имена томов сети, номера телефонов, имена учетных записей пользователей и т. д. Если подключение к хранилищу не может быть выполнено с помощью данных в идентификаторе записи, поставщик хранилища должен отобразить диалоговое окно, позволяющее пользователю выбрать открываемое хранилище. Может потребоваться диалоговое окно, например, если сервер был переименован, имя учетной записи изменено или части сети недоступны.
Если lpEntryID имеет значение NULL, хранилище сообщений для использования еще не выбрано. Поставщик по-прежнему может получить доступ к хранилищу без отображения диалогового окна, если он поддерживает дополнительные методы для указания хранилища. Например, поставщик может проверка файл инициализации или искать дополнительные свойства, которые были помещены в раздел профиля службы сообщений при настройке.
Если поставщик обнаружит, что все необходимые сведения отсутствуют в профиле, он должен вернуть MAPI_E_UNCONFIGURED. Затем MAPI вызовет функцию точки входа службы сообщений поставщика, чтобы позволить пользователю выбрать хранилище или даже создать его, а также ввести имя учетной записи и пароль при необходимости. MAPI автоматически создает раздел профиля для нового хранилища; Этот новый раздел профиля может быть временным или постоянным в зависимости от того, как он был добавлен. Если поставщик хранилища вызывает метод IMAPISupport::ModifyProfile , новый раздел профиля становится постоянным и хранилище добавляется в список хранилищ сообщений, возвращаемых методом IMAPISession::GetMsgStoresTable .
Параметр lpInterface указывает IID интерфейса, необходимого для только что открытого объекта хранилища. Передача null в lpInterface указывает, что требуется интерфейс хранилища сообщений MAPI IMsgStore. Передача объекта хранилища сообщений IID_IMsgStore также указывает, что требуется IMsgStore . Если IID_IUnknown передается в lpInterface, поставщик должен открыть хранилище, используя интерфейс, производный от IUnknown , который лучше всего подходит для поставщика (опять же, это IMsgStore). При передаче IID_IUnknown вызывающая реализация использует метод IUnknown::QueryInterface для выбора интерфейса после успешной операции открытия хранилища.
Вызов IMSProvider::Logon должен возвращать достаточно сведений, таких как путь к хранилищу и учетные данные для доступа к хранилищу, чтобы разрешить spooler MAPI войти в то же хранилище, что и поставщик хранилища, не открыв диалоговое окно. Для возврата этих сведений используются параметры lpcbSpoolSecurity и lppbSpoolSecurity . Поставщик выделяет память для этих данных путем передачи указателя на буфер в параметре lpfAllocateBuffer функции MSProviderInit; поставщик помещает размер этого буфера в lpcbSpoolSecurity.
MAPI освобождает этот буфер при необходимости. Если вход диспетчера очереди MAPI в хранилище можно выполнить только из сведений в разделе профиля, поставщик может вернуть значение NULL в lppbSpoolSecurity и 0 для размера сведений в lpcbSpoolSecurity. Вход в очередь MAPI выполняется как часть процесса, отличного от процесса входа в хранилище. Так как буфер, содержащий переданную информацию, копируется между процессами, он может находиться в памяти в том же расположении для процесса диспетчера очереди MAPI, что и для процесса поставщика хранилища. Поэтому поставщик не должен помещать адреса в этот буфер. Дополнительные сведения о входе в mapI spooler см. в статье Метод IMSProvider::SpoolerLogon .
Большинство поставщиков хранилища используют метод IMAPISession::OpenProfileSection объекта поддержки, переданного в параметре lpMAPISup , для сохранения и получения учетных данных и параметров пользователя. OpenProfileSection позволяет поставщику хранилища сохранять дополнительные произвольные сведения в разделе профиля и связывать их с определенным ресурсом. Например, поставщик хранилища может сохранить имя учетной записи пользователя и пароль, связанные с ресурсом, а также любые пути или другие сведения, необходимые для доступа к нему.
Свойства с идентификаторами свойств 0x6600 через 0x67FF являются безопасными свойствами, доступными поставщику для собственного использования для хранения частных данных в разделах профиля. Дополнительные сведения об использовании свойств в объектах раздела профиля см. в статье Метод IProfSect : IMAPIProp .
Помимо личных данных в свойствах с идентификаторами, 0x6600 через 0x67FF, поставщик хранилища должен предоставить сведения о свойстве PR_DISPLAY_NAME (PidTagDisplayName) в разделе профиля. Он должен поместить в PR_DISPLAY_NAME отображаемое имя самого поставщика — идентификационную строку (например, "Хранилище персональных данных Майкрософт"), которая отображается для пользователей, чтобы они могли отличать это хранилище сообщений от других, к которым у них может быть доступ. PR_DISPLAY_NAME обычно содержит имя сервера, имя учетной записи пользователя или путь.
Некоторые свойства раздела профиля отображаются в таблице хранилища сообщений; другие видны во время установки, установки и настройки подсистемы MAPI. Поставщик обычно предоставляет сведения об этих видимых свойствах как для нового раздела профиля, который еще не содержит сохраненных учетных данных или личных сведений, так и при обнаружении изменения сведений о свойствах. Дополнительные сведения о разделах профилей см. в разделе IMAPISupport::OpenProfileSection.
После успешного входа в систему пользователя и перед возвращением в MAPI поставщик хранилища должен создать массив свойств для строки состояния ресурса и вызвать метод IMAPISupport::ModifyStatusRow .
Вызовы входа , которые открывают хранилища сообщений, которые уже открыты для текущего сеанса MAPI, пропускают большую часть описанной выше обработки. Эти вызовы не создают строки состояния, не возвращают объекты для входа в систему, не вызывают AddRef для объекта поддержки MAPI или возвращают данные для входа в систему mapI spooler. Эти вызовы возвращают S_OK и возвращают объект хранилища сообщений с запрошенным интерфейсом.
Для обнаружения таких вызовов поставщик должен вести список в объекте поставщика хранилища сообщений хранилищ, которые уже открыты для этого объекта поставщика. При обработке вызова входа поставщик должен проверить этот список открытых хранилищ и определить, открыто ли хранилище, в котором выполняется вход. Если это так, учетные данные пользователя не нужно проверять, и по возможности следует избегать отображения диалогового окна. Если должны отображаться диалоговые окна, поставщик должен проверка возвращенные сведения, чтобы узнать, было ли хранилище открыто во второй раз. Кроме того, поставщик должен проверка для повторяющихся открытий с помощью lpEntryID в начале обработки вызова входа.
Стандартная обработка для вызова входа , который обращается к открытому хранилищу, выглядит следующим образом:
Поставщик хранилища вызывает AddRef для существующего объекта хранилища, если запрашиваемый новый интерфейс совпадает с интерфейсом для существующего хранилища. В противном случае он вызывает QueryInterface для получения нового интерфейса. Если хранилище не поддерживает новый интерфейс, поставщик должен вернуть значение ошибки MAPI_E_INTERFACE_NOT_SUPPORTED.
Поставщик возвращает указатель на необходимый интерфейс существующего объекта хранилища в lppMDB.
Поставщик возвращает значение NULL в lppMSLogon.
Поставщик не должен открывать профиль для объекта поддержки, переданного в вызове. Кроме того, он не должен регистрировать уникальный идентификатор поставщика, регистрировать строку состояния или возвращать данные о входе в диспетчер очереди MAPI.
Поставщик не должен вызывать AddRef для объекта поддержки, так как ему не требуется указатель на объект .
По возможности поставщики должны возвращать соответствующие строки ошибок и предупреждений для вызовов входа , так как это значительно упрощает нагрузку пользователей при определении причин, по которой что-то не работает. Чтобы вернуть эти строки, поставщик задает члены в структуре MAPIERROR . MAPI ищет, использует и освобождает структуру MAPIERROR , если она возвращается поставщиком.
Память для этой структуры MAPIERROR должна выделяться с помощью буфера, переданного в lpfAllocateBuffer при вызове MSProviderInit . Все строки ошибок, содержащиеся в возвращаемой структуре, должны быть в формате Юникода, если MAPI_UNICODE задано в ulFlagsдля входа; в противном случае они должны быть в кодировке ANSI.
Для большинства значений ошибок, возвращаемых при входе в систему, MAPI отключает службы сообщений, к которым принадлежит поставщик ошибок. MAPI не будет вызывать поставщиков, принадлежащих этим службам в течение всего времени существования сеанса MAPI. В отличие от этого, когда вход в систему возвращает значение ошибки MAPI_E_FAILONEPROVIDER из своего входа, MAPI не отключает службу сообщений, к которой принадлежит поставщик. Вход должен возвращать MAPI_E_FAILONEPROVIDER, если возникает ошибка, не требующая отключения всей службы в течение всего сеанса. Например, поставщик может вернуть эту ошибку, если он не разрешает отображение пользовательского интерфейса и необходимый пароль недоступен.
Если поставщик возвращает MAPI_E_UNCONFIGURED из входа, MAPI вызовет функцию входа в службу сообщений поставщика, а затем повторите вход. MAPI передает MSG_SERVICE_CONFIGURE в качестве контекста, чтобы дать службе возможность настроить себя. Если клиент решил разрешить пользовательский интерфейс при входе, служба может представить свой лист свойств конфигурации, чтобы пользователь смог ввести сведения о конфигурации.
См. также
IMAPISession::GetMsgStoresTable