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
[in]指向消息存储的当前 MAPI 支持对象的指针。
ulUIParam
[in]此方法显示的任何对话框或窗口的父窗口的句柄。
lpszProfileName
[in]指向字符串的指针，该字符串包含用于存储提供程序登录的配置文件的名称。 此字符串可以显示在对话框中、写出到日志文件中或直接忽略。 如果在 ulFlags 参数中设置了MAPI_UNICODE标志，则它必须采用 Unicode 格式。
cbEntryID
[in] lpEntryID 参数指向的条目标识符的大小（以字节为单位）。
lpEntryID
[in]指向消息存储的条目标识符的指针。 在 lpEntryID 中传递 null 表示尚未选择消息存储，并且可以显示允许用户选择消息存储的对话框。
ulFlags
[in]控制如何执行登录的标志的位掩码。 可以设置以下标志：
MAPI_DEFERRED_ERRORS
即使基础对象对调用实现不可用，也允许调用成功。 如果该对象不可用，则对对象的后续调用可能会引发错误。
MAPI_UNICODE
传入的字符串采用 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
[in]指向要登录的消息存储的接口标识符 (IID) 的指针。 传递 null 表示返回 IMsgStore) ( 消息存储的 MAPI 接口。 还可以将 lpInterface 参数设置为消息存储 (适当接口的标识符，例如，IID_IUnknown或IID_IMAPIProp) 。
l池安全性
[out]指向变量的指针，其中存储提供程序返回 lppbSpoolSecurity 参数中验证数据的大小（以字节为单位）。
lppbSpoolSecurity
[out]指向返回的验证数据的指针的指针。 提供此验证数据，以便 IMSProvider：：SpoolerLogon 方法可以将 MAPI 后台处理程序记录到与消息存储提供程序相同的存储区。
lppMAPIError
[out]指向返回的 MAPIERROR 结构的指针（如果有）的指针，该结构包含错误的版本、组件和上下文信息。 如果没有要返回的 MAPIERROR 结构，可以将 lppMAPIError 参数设置为 null。
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 方法以执行获取对消息存储的访问权限所需的大部分处理。 消息存储提供程序验证访问特定存储所需的任何用户凭据，并在 MAPI 后台处理程序和客户端应用程序可以登录的 lppMDB 参数中返回消息存储对象。
除了客户端和 MAPI 后台处理程序使用的返回的消息存储对象外，提供程序还返回 MAPI 的消息存储登录对象，用于控制打开的存储区。 消息存储登录对象和消息存储对象应紧密链接在消息存储提供程序内，以便每个对象都可能影响另一个。 存储对象的使用和登录对象应相同;登录对象和存储对象之间应有一对一的对应关系，使对象就像是公开两个接口的一个对象一样运行。 这两个对象也应一起创建并一起释放。
MAPI 支持对象（由 MAPI 创建并传递给 lpMAPISup 参数中的提供程序）提供对 MAPI 中提供程序所需的函数的访问。 其中包括保存和检索配置文件信息、访问通讯簿等的函数。 对于打开的每个存储区， lpMAPISup 指针可能不同。 在登录后处理对消息存储的调用时，存储提供程序应使用特定于该存储的 lpMAPISup 变量。 对于打开消息存储并成功创建消息存储登录对象的任何 Logon 调用，提供程序必须在存储登录对象中保存指向 MAPI 支持对象的指针，并且必须调用 IUnknown：：AddRef 方法来添加对支持对象的引用。
如果提供程序在登录调用期间显示对话框，则应使用 ulUIParam 参数。 但是，如果 ulFlags 包含MDB_NO_DIALOG标志，则不应显示对话框。 如果需要调用用户界面，但 ulFlags 不允许它，或者由于某种其他原因无法显示用户界面，提供程序应返回MAPI_E_LOGON_FAILED。 如果 Logon 显示对话框，并且用户取消登录（通常是通过单击对话框的“ 取消 ”按钮），提供程序应返回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。 在 lpInterface 中传递 null 指定需要 MAPI 消息存储接口 IMsgStore。 传递消息存储对象（IID_IMsgStore）还指定需要 IMsgStore 。 如果在 lpInterface 中传递IID_IUnknown，则提供程序应使用派生自 IUnknown 的任何接口打开存储区，该接口最适合提供程序 (，这通常是 IMsgStore) 。 传递IID_IUnknown时，调用实现在存储打开操作成功后使用 IUnknown：：QueryInterface 方法选择接口。
IMSProvider：：Logon 调用应返回足够的信息（例如存储的路径和用于访问存储的凭据），以允许 MAPI 后台处理程序登录到存储提供程序不显示对话框的同一存储区。 l池Security 和 lppbSpoolSecurity 参数用于返回此信息。 提供程序通过传递 指向 MSProviderInit 函数 的 lpfAllocateBuffer 参数中的缓冲区的指针来分配此数据的内存;提供程序将此缓冲区的大小置于 lSecurity 中。
MAPI 在适当时释放此缓冲区。 如果 MAPI 后台处理程序对存储的登录可以仅从配置文件部分中的信息完成，则提供程序可以在 lppbSpoolSecurity 中返回 null，对于 lbSpoolSecurity 中的信息大小返回 0。 MAPI 后台处理程序登录作为与存储登录不同的过程的一部分进行;因为包含传递信息的缓冲区在进程之间复制，所以它可能不在 MAPI 后台处理程序进程与存储提供程序进程相同的位置的内存中。 因此，提供程序不应将地址放入此缓冲区。 有关 MAPI 后台处理程序登录的详细信息，请参阅 IMSProvider：：SpoolerLogon 方法。
大多数存储提供程序使用 lpMAPISup 参数中传递的支持对象的 IMAPISession：：OpenProfileSection 方法来保存和检索用户凭据和选项。 OpenProfileSection 使存储提供程序能够在配置文件节中保存其他任意信息，并将其与特定资源相关联。 例如，存储提供程序可以保存与资源关联的用户帐户名和密码，以及访问该资源所需的任何路径或其他信息。
通过 0x67FF 0x6600属性标识符的属性是提供程序可用于在配置文件节中存储私有数据的安全属性。 有关在配置文件部分对象中使用属性的详细信息，请参阅 IProfSect ：IMAPIProp 方法。
除了具有通过0x67FF 0x6600标识符的属性中的任何私有数据外，存储提供程序还应在其配置文件部分中提供 PR_DISPLAY_NAME (PidTagDisplayName) 属性的信息。 它应输入 PR_DISPLAY_NAME 提供程序本身的显示名称-标识字符串 (例如，“Microsoft 个人信息存储”) 显示给用户，以便他们能够将此消息存储区与其可能有权访问的其他消息区区分开来。 PR_DISPLAY_NAME 通常包含服务器名称、用户帐户名称或路径。
某些配置文件节属性在消息存储表中可见;在 MAPI 子系统的安装、安装和配置过程中，可以看到其他内容。 提供程序通常为新配置文件部分（尚不包括保存的凭据或私有信息）以及发现属性信息已更改时提供这些可见属性的信息。 有关配置文件部分的详细信息，请参阅 IMAPISupport：：OpenProfileSection。
成功登录用户后，在返回到 MAPI 之前，存储提供程序应为资源的状态行创建属性数组，并调用 IMAPISupport：：ModifyStatusRow 方法。
打开已为当前 MAPI 会话打开的消息存储的登录调用会跳过前面所述的大部分处理。 这些调用不会创建状态行、返回消息存储登录对象、为 MAPI 支持对象调用 AddRef 或返回 MAPI 后台处理程序登录的数据。 这些调用返回S_OK，并返回具有所请求接口的消息存储对象。
若要检测此类调用，提供程序应维护已为此提供程序对象打开的存储区的消息存储提供程序对象中的列表。 处理 登录 调用时，提供程序应扫描此打开的存储列表，并确定要登录的存储是否已打开。 如果是，则无需检查用户凭据，如果可能，应避免显示对话框。 如果必须显示对话框，提供程序应检查返回的信息，以查看是否已第二次打开商店。 此外，提供程序应在登录调用处理开始时使用 lpEntryID 检查重复的开口。
访问开放存储的 登录 调用的标准处理如下：
如果请求的新接口与现有存储的接口相同，则存储提供程序为现有存储对象调用 AddRef 。 否则，它会调用 QueryInterface 来获取新接口。 如果存储不支持新接口，则提供程序应MAPI_E_INTERFACE_NOT_SUPPORTED返回错误值。
提供程序返回指向 lppMDB 中现有存储对象的所需接口的指针。
提供程序在 lppMSLogon 中返回 null。
提供程序不应打开调用中传递的支持对象的配置文件。 此外，它不应注册提供程序唯一标识符、注册状态行或返回 MAPI 后台处理程序登录数据。
提供程序不应为支持对象调用 AddRef ，因为它不需要指向 对象的指针。
提供商应尽可能为 登录 调用返回相应的错误和警告字符串，因为这样做可大大减轻用户在确定某些内容不起作用的原因方面的负担。 若要返回这些字符串，提供程序设置 MAPIERROR 结构中的成员。 如果 MAPI 由提供程序返回，则 MAPI 会查找、使用和释放 MAPIERROR 结构。
应在 MSProviderInit 调用上使用 lpfAllocateBuffer 中传递的缓冲区来分配此 MAPIERROR 结构的内存。 如果在 LogonulFlags 中设置了MAPI_UNICODE，则返回结构中包含的任何错误字符串都应采用 Unicode 格式;否则，它们应位于 ANSI 字符集中。
对于从 Logon 返回的大多数错误值，MAPI 禁用失败提供程序所属的消息服务。 在 MAPI 会话的生命周期内，MAPI 不会调用属于这些服务的任何提供程序。 相反，当 Logon 从登录返回MAPI_E_FAILONEPROVIDER错误值时，MAPI 不会禁用提供程序所属的消息服务。 如果登录遇到错误，该错误不保证在会话的生命周期内禁用整个服务，则登录应返回MAPI_E_FAILONEPROVIDER。 例如，如果提供程序不允许显示用户界面，并且所需的密码不可用，则可能会返回此错误。
如果提供程序从登录返回MAPI_E_UNCONFIGURED，MAPI 将调用提供程序的消息服务条目函数，然后重试登录。 MAPI 传递MSG_SERVICE_CONFIGURE作为上下文，使服务有机会配置自身。 如果客户端已选择允许登录时使用用户界面，则服务可以显示其配置属性表，以便用户可以输入配置信息。
另请参阅
IMAPISession::GetMsgStoresTable