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标志,MAPILogonEx 将使用现有的共享会话,即使 lpszprofileName 参数不是 NULL。

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 调用和从 MAPI 调用返回的所有字符串均为 null 终止,必须在调用客户端或提供程序操作系统的当前字符集或代码页中指定。

如果存在名为 MapiLogonEx 且已设置MAPI_ALLOW_OTHERS标志的现有会话,并且未设置标志MAPI_NEW_SESSION,则忽略 lpszProfileName 参数。 如果 lpszProfileName 参数为 NULL 或指向空字符串,并且 flFlags 参数包含MAPI_LOGON_UI标志,则 MAPILogonEx 函数将生成一个具有配置文件名称空字段的登录对话框。

登录到特定配置文件时,除了配置文件名称之外,客户端还应将MAPI_NEW_SESSION标志传递到 MAPILogonEx 中。 否则,如果另一个客户端通过使用 MAPI_ALLOW_OTHERS 登录来建立共享会话,则客户端将登录到共享会话,而不是所请求的配置文件。

MAPI_EXPLICIT_PROFILE标志不会导致在 lpszProfileName 为 NULL 或空时使用默认配置文件名称,除非同时存在MAPI_USE_DEFAULT标志。

不使用 MAPI 后台处理程序时,MAPI_NO_MAIL标志具有多种效果,导致以下情况:

  • 在此会话期间,MAPI 后台处理程序无法发送或传递任何消息。 只有紧密耦合的存储和传输提供程序才能发送和传递消息。

  • 基于服务器的存储仍可能发送或传递消息。

  • 基于服务器的存储发送或传递的消息不会由任何挂钩提供程序处理。

  • 传输的“每消息”和“每个收件人”选项不可用。

  • 状态表不包含传输提供程序的条目,并且任何依赖于状态对象的传输功能 ((如配置) )不可用。

  • 状态表中的消息后台处理程序行包含STATUS_FAILURE值。

  • 允许使用 Piggybacked 登录,但这些登录不会导致以前的登录接收状态对象更新。

服务应始终使用MAPI_NO_MAIL标志登录。

MFCMAPI 引用

有关 MFCMAPI 示例代码,请参阅下表。

文件 函数 备注
MAPIObjects.cpp
CMapiObjects::MAPILogonEx
MFCMAPI 使用 MAPILogonEx 方法登录到 MAPI。

另请参阅

IMAPISession::GetMsgStoresTable

IMAPISession::OpenMsgStore

MFCMAPI 代码示例