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
[in]指向通讯簿提供程序的支持对象的指针。
ulUIParam
[in]登录 方法显示的 登录对话框的父窗口的句柄（如果允许）。 ulUIParam 参数包含在上一次对 MAPILogonEx 函数的调用中传递给 MAPI 的同名参数的值。
lpszProfileName
[in]指向会话配置文件名称的指针。
ulFlags
[in]控制如何执行登录的标志的位掩码。 可以设置以下标志：
AB_NO_DIALOG
登录期间，提供程序不应显示对话框。 如果未设置此标志，提供程序可以显示一个对话框来提示用户缺少配置信息。
MAPI_DEFERRED_ERRORS
启用 登录 以成功返回，可能是在登录过程完成之前。
MAPI_UNICODE
所有字符串都应采用 Unicode 格式。 如果未设置MAPI_UNICODE标志，则字符串应采用 ANSI 格式。
lpulcbSecurity
[in，out]指向 lppbSecurity 参数指向的安全凭据结构的大小（以字节为单位）的指针。 输入时，该值必须为非零;输出时，该值必须为零。 在这两种情况下，指针都必须有效。
lppbSecurity
[in，out]指向指向安全凭据的指针的指针。 输入时，该值必须为非零;输出时，该值必须为零。 在这两种情况下，指针都必须有效。
lppMAPIError
[out]指向 MAPIERROR 结构的指针的指针。 如果没有要返回的 MAPIERROR 结构，可以将 lppMAPIError 参数设置为 NULL。
lppABLogon
[out]指向提供程序登录对象的指针的指针的指针。
返回值
S_OK
已成功建立与活动会话的连接。
MAPI_E_FAILONEPROVIDER
提供程序无法登录，但 MAPI 可以继续登录到提供程序所属的消息服务中的其他提供程序。
MAPI_E_UNCONFIGURED
提供程序的信息不足，无法完成登录。 MAPI 调用提供程序的消息服务入口函数。
MAPI_E_UNKNOWN_CPID
服务器未配置为支持客户端的代码页。
MAPI_E_UNKNOWN_LCID
服务器未配置为支持客户端的区域设置信息。
MAPI_E_USER_CANCEL
用户取消了操作，通常单击登录对话框中的“ 取消 ”按钮。
备注
当客户端调用 IMAPISession：：OpenAddressBook 方法时，将使用会话配置文件中的每个通讯簿提供程序建立Connections。 然后，OpenAddressBook 调用每个提供程序的 Logon 方法。
lpszProfileName 参数指向的配置文件名称显示在用户客户端的字符集中，如 ulFlags 参数中是否存在MAPI_UNICODE标志所指示的那样。
针对实现者的说明
在 Logon 方法的实现中，调用 IMAPISupport：：SetProviderUID 方法来注册唯一标识符或 MAPIUID 结构。 每个对象都将具有包含此 MAPIUID 的条目标识符。 MAPI 使用 MAPIUID 将对象与其提供程序匹配。 例如，当客户端调用 IMAPISession：：OpenEntry 方法以打开消息传递用户时， OpenEntry 会检查传入的条目标识符的 MAPIUID 部分，并将其与通讯簿提供程序注册的 MAPIUID 匹配。
如果客户端多次登录到提供程序，可能需要为每次登录注册不同的 MAPIUID 。 注册唯一 的 MAPIUID 结构使 MAPI 能够将请求正确路由到相应的提供程序实例。 但是，你可能希望每个登录对象共享一个 MAPIUID。 在这种情况下，必须能够自行处理路由，而不是依赖于 MAPI。 有关如何创建 MAPIUID 的详细信息，请参阅 注册服务提供程序唯一标识符。
MAPI 在 lpMAPISup 参数中传递给 Logon 方法的支持对象提供对 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 会重试登录。