MAPILogonEx
适用于：Outlook 2013 | Outlook 2016
将客户端应用程序记录到与消息传送系统的会话。
| 属性 | 值 |
|---|---|
| 标头文件： |
Mapix.h |
| 实现者： |
MAPI |
| 调用者： |
客户端应用程序 |
HRESULT MAPILogonEx(
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
LPSTR lpszPassword,
FLAGS flFlags,
LPMAPISESSION FAR * lppSession
);
参数
ulUIParam
[in]登录对话框处于模式的窗口的句柄。 如果在调用过程中未显示任何对话框，则忽略 ulUIParam 参数。 此参数可以为零。
lpszProfileName
[in]指向包含用户登录时要使用的配置文件名称的字符串的指针。 此字符串长度为 64 个字符限制。
lpszPassword
[in]指向包含配置文件密码的字符串的指针。 lpszPassword 参数必须为 NULL。
flFlags
[in]用于控制如何执行登录的标志的位掩码。 可以设置以下标志：
MAPI_ALLOW_OTHERS
应返回共享会话，这样以后的客户端无需提供任何用户凭据即可获取会话。
MAPI_BG_SESSION
登录到会话并在后台运行任何操作。 通常，如果客户端打算在后台线程或单独的进程中以对前台线程不显眼的方式执行处理，则客户端应使用 MAPI_BG_SESSION 标志调用 。 客户端应用程序（如索引引擎或打开个人文件夹文件 (PST) 进行后台类型访问）是使用MAPI_BG_SESSION的位置的一些示例。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标志，即使 lpszprofileName 参数不为 NULL，MAPILogonEx 也会使用现有的共享会话。
MAPI_NO_MAIL
MAPI 不应通知 MAPI 后台处理程序会话的存在。 结果是，除了通过紧密耦合的存储和传输对之外，会话中无法发送或接收任何消息。 如果调用客户端充当代理、必须完成配置工作或客户端正在浏览可用消息存储，则调用客户端将设置此标志。
MAPI_NT_SERVICE
调用方作为 Windows 服务运行。 未作为 Windows 服务运行的调用方不应设置此标志;作为服务运行的调用方必须设置此标志。
MAPI_SERVICE_UI_ALWAYS
MAPILogonEx 应显示配置文件中每个消息服务的配置对话框。 在选择配置文件之后，但在登录任何消息服务之前，将显示这些对话框。 用于登录的 MAPI 通用对话框还包含请求相同操作的检查框。
MAPI_TIMEOUT_SHORT
如果被阻止的时间超过几秒钟，则登录应会失败。
MAPI_UNICODE
传入的字符串采用 Unicode 格式。 如果未设置MAPI_UNICODE标志，则字符串采用 ANSI 格式。
MAPI_USE_DEFAULT
消息子系统应将默认配置文件的配置文件名称替换为 lpszProfileName 参数。 除非 lpszProfileName 为 NULL 或空，否则将忽略MAPI_EXPLICIT_PROFILE标志。
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 结尾，必须在调用客户端或提供程序操作系统的当前字符集或代码页中指定。
如果存在调用 MapiLogonEx 的现有会话且设置了 MAPI_ALLOW_OTHERS 标志，并且未设置MAPI_NEW_SESSION标志，则忽略 lpszProfileName 参数。 如果 lpszProfileName 参数为 NULL 或指向空字符串，并且 flFlags 参数包含 MAPI_LOGON_UI 标志，则 MAPILogonEx 函数将生成一个登录对话框，该对话框具有配置文件名称的空字段。
登录到特定配置文件时，客户端除了配置文件名称外，还应将 MAPI_NEW_SESSION 标志传递到 MAPILogonEx 中。 否则，如果另一个客户端使用 MAPI_ALLOW_OTHERS 登录建立了共享会话，则客户端将登录到共享会话，而不是登录到请求的配置文件。
当 lpszProfileName 为 NULL 或空时，MAPI_EXPLICIT_PROFILE标志不会导致使用默认配置文件名称，除非同时存在MAPI_USE_DEFAULT标志。
不使用 MAPI 后台处理程序时，MAPI_NO_MAIL标志具有多种影响，导致以下问题：
在此会话期间，MAPI 后台处理程序无法发送或传递任何消息。 只有紧密耦合的存储和传输提供程序才能发送和传递消息。
基于服务器的存储仍可能发送或传递消息。
基于服务器的存储发送或传递的消息不会由任何挂钩提供程序处理。
传输的每封邮件和按收件人选项不可用。
状态表不包含传输提供程序的条目，任何依赖于状态对象 (的传输功能（如配置) ）都不可用。
状态表中的消息后台处理程序行包含STATUS_FAILURE值。
允许使用 Piggybacked 登录，但这些登录不会导致以前的登录接收状态对象更新。
服务应始终使用 MAPI_NO_MAIL 标志登录。
MFCMAPI 引用
有关 MFCMAPI 示例代码，请参阅下表。
| 文件 | 函数 | Comment |
|---|---|---|
| MAPIObjects.cpp |
CMapiObjects：：MAPILogonEx |
MFCMAPI 使用 MAPILogonEx 方法登录到 MAPI。 |