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，例如，在 lpulFlags 参数中设置了 LOGON_SETUP 标志时。
lpszProfileName： [in] 指向用户的配置文件名称的指针。 lpszProfileName 参数主要用于必须显示对话框时。
lpulFlags： [in， out] 用于控制如何建立登录会话的标志的位掩码。 MAPI 后台处理程序可以在输入时设置以下标志：
LOGON_NO_CONNECT：用户帐户登录到此传输提供程序的目的不是为了传输和接收消息。 传输提供程序不应尝试与其他消息传送系统建立任何连接。
LOGON_NO_DIALOG：即使当前保存的用户凭据无效或不足以登录，也不应显示任何对话框。
LOGON_NO_INBOUND：传输提供程序不必初始化消息接收，也不应接受传入消息。 MAPI 后台处理程序稍后可以使用 IXPLogon：：TransportNotify 方法向传输提供程序发出信号，以启用传入消息处理。
LOGON_NO_OUTBOUND：传输提供程序不必初始化来发送消息，因为 MAPI 后台处理程序不提供任何消息。 如果客户端应用程序在撰写消息期间需要连接到远程提供程序，以便它可以进行 IXPLogon：：AddressTypes 方法调用，则传输提供程序应建立连接。 当传出操作开始时，MAPI 后台处理程序可以使用 TransportNotify 向传输提供程序发出信号。
MAPI_UNICODE：配置文件名称的传入字符串采用 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 结构中返回的字符串（如果有）采用 Unicode 格式。 如果未设置MAPI_UNICODE标志，则字符串采用 ANSI 格式。
lppMAPIError： [out] 指向返回的 MAPIERROR 结构的指针（如果有），该结构包含错误的版本、组件和上下文信息。 如果没有要返回的 MAPIERROR 结构，可以将 lppMAPIError 参数设置为 NULL。
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 方法为用户建立登录会话。
大多数传输提供程序使用 lpMAPISup 参数指向的支持对象提供的 IMAPISupport：：OpenProfileSection 方法来保存和检索用户标识信息、服务器地址和凭据。 通过使用 OpenProfileSection，传输提供程序可以保存任意信息并将其与登录到特定资源相关联。 例如，提供程序可以使用 OpenProfileSection 保存与特定会话关联的帐户名和密码，以及访问该会话的资源所需的任何服务器名称或其他必要信息。 MAPI 对外部访问隐藏与资源关联的信息。 通过 lpMAPISup 提供的配置文件部分由 MAPI 后台处理程序管理，因此与此用户上下文相关的数据与其他上下文的数据分开。
传输提供程序必须在支持对象上调用 IUnknown：：AddRef 方法，并将指向此对象的指针的副本保留为提供程序登录对象的一部分。
提供了 lpszProfileName 中的配置文件显示名称，以便传输提供程序可以在错误消息或登录对话框中使用它。 如果提供程序保留此名称，则必须将其复制到提供程序分配的存储中。
与其他服务提供商紧密耦合的传输提供程序可能需要在登录时执行其他工作，以建立在配套提供程序之间进行操作所需的良好凭据。
通常，当用户首次登录到配置文件时，会打开传输提供程序。 因此，由于首次登录到配置文件通常在登录到任何消息存储之前进行，因此 MAPI 后台处理程序通常使用在 lpulFlags 中设置的LOGON_NO_INBOUND和LOGON_NO_OUTBOUND标志调用 TransportLogon。 稍后，当配置文件会话中提供了相应的消息存储时，MAPI 后台处理程序会调用 TransportNotify 来启动传输提供程序的传入和传出操作。
在 lpulFlags 中传递LOGON_NO_CONNECT标志表示传输提供程序的脱机操作。 此标志指示不应建立外部连接;如果传输提供程序在没有外部连接的情况下无法建立会话，则应返回登录的错误值。
如果传输提供程序设计为使用系统在其他情况下处于空闲状态的时间，则应在初始化时在 lpulFlags 中设置LOGON_SP_IDLE标志。 此类时间通常用于处理自动操作，例如自动消息下载、计时消息下载或计时消息提交。 如果设置了此标志，则 MAPI 后台处理程序在发生系统空闲时间时调用 Idle 来启动此类操作。 MAPI 后台处理程序不以设置的间隔调用 Idle ;相反，仅在真正的空闲时间调用它。 因此，提供程序不应基于有关其 Idle 方法调用频率的任何假设。 支持空闲时间操作的提供程序应在其提供程序属性表中为其提供配置用户界面。
如果传输提供程序登录成功，则提供程序应在 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 调用提供程序的消息服务入口点函数。