IMAPIStatus::ValidateState
适用于：Outlook 2013 | Outlook 2016
确认 MAPI 资源或服务提供程序可用的外部状态信息。 所有状态对象都支持此方法。
HRESULT ValidateState(
ULONG_PTR ulUIParam,
ULONG ulFlags
);
参数
ulUIParam
[in]此方法显示的任何对话框或窗口的父窗口的句柄。
ulFlags
[in]控制验证的标志的位掩码。 可以设置以下标志：
ABORT_XP_HEADER_OPERATION
用户取消了操作，通常单击相应对话框中的“ 取消 ”按钮。 status 对象有两个选项：
继续处理操作。
停止操作并返回MAPI_E_USER_CANCELED。
CONFIG_CHANGED
状态对象的一个或多个配置属性已更改。 客户端可以设置此标志，以允许 MAPI 后台处理程序动态更正关键传输提供程序故障。
FORCE_XP_CONNECT
状态对象应执行连接。 当此标志与 REFRESH_XP_HEADER_CACHE 或 PROCESS_XP_HEADER_CACHE 标志一起使用时，连接将不进行缓存。
FORCE_XP_DISCONNECT
状态对象应执行断开连接操作。 当此标志与 REFRESH_XP_HEADER_CACHE 或 PROCESS_XP_HEADER_CACHE 标志一起使用时，断开连接时不进行缓存。
PROCESS_XP_HEADER_CACHE
应处理标头缓存表中的条目，应下载标有 MSGSTATUS_REMOTE_DOWNLOAD 标志的所有消息，并删除所有使用 MSGSTATUS_REMOTE_DELETE 标志标记的消息。 应移动同时设置了MSGSTATUS_REMOTE_DOWNLOAD和MSGSTATUS_REMOTE_DELETE的邮件。
REFRESH_XP_HEADER_CACHE
对于远程传输提供程序，应下载新的消息标头列表，并清除标记消息状态的所有标志。
SUPPRESS_UI
防止状态对象在操作过程中显示用户界面。
返回值
S_OK
验证成功。
MAPI_E_BUSY
另一个操作正在进行中;在启动此操作之前，应允许它完成，或者应停止它。
MAPI_E_NO_SUPPORT
状态对象不支持验证方法，如 PR_RESOURCE_METHODS (PidTagResourceMethods) 属性中缺少 STATUS_VALIDATE_STATE 标志所示。
MAPI_E_USER_CANCEL
用户取消了验证操作，通常单击对话框中的“ 取消 ”按钮。 此值仅由远程传输提供程序返回。
备注
IMAPIStatus：：ValidateState 方法检查与状态对象关联的资源的状态。 ValidateState 是 IMAPIStatus 接口中所有状态对象所需的唯一方法。 此方法的确切行为取决于实现。 下表描述了每种不同类型的状态对象的实现。
| Status 对象 | ValidateState 实现 |
|---|---|
| MAPI 子系统 |
验证当前活动服务提供程序和子系统本身拥有的所有资源的状态。 |
| MAPI 后台处理程序 |
对所有传输提供程序执行登录，无论它们是否已登录。 |
| MAPI 通讯簿 |
检查其配置文件部分中的条目。 |
| 服务提供商 |
实现取决于提供程序的类型和 ulFlags 参数中设置的标志。 |
针对实现者的说明
远程客户端应用程序调用 ValidateState 方法以启动各种操作的远程处理。 此方法主要用于设置状态位以与 MAPI 后台处理程序通信，而不是实际执行任何工作。 通常，传输提供程序在其状态行中设置标志，向 MAPI 后台处理程序指示需要启动哪些操作才能完成客户端的请求。
在此客户端-传输-后台处理程序交互模型中，客户端请求的操作是异步的，其中 ValidateState 在请求的操作完成之前返回。 但是，不一定涉及基础消息传送系统或涉及特定于传输的接口的操作可以是同步的。 客户端应用程序传入以下标志的位掩码，以指定远程传输提供程序应执行的操作。
ABORT_XP_HEADER_OPERATION
如果可能，远程传输提供程序应取消任何涉及下载标头的操作。 为此，传输提供程序必须在登录对象的状态行中设置以下属性值：
清除 PR_STATUS_CODE (PidTagStatusCode) 属性中的STATUS_INBOUND_ENABLED位和STATUS_INBOUND_ACTIVE位，以指示 MAPI 后台处理程序停止此传输提供程序的传入刷新过程。
在 PR_STATUS_CODE 属性中设置 STATUS_OFFLINE 位。
将 PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) 属性设置为 TRUE。
将 PR_STATUS_STRING (PidTagStatusString) 属性设置为一个字符串，以向用户指示传输提供程序的状态。
返回S_OK。 但是，如果无法取消正在进行的操作， ValidateState 应返回MAPI_E_BUSY。
FORCE_XP_CONNECT
远程传输提供程序不应 (与共享资源建立连接，例如，调制解调器或 COM 端口) IXPLogon：：FlushQueues 方法中涉及的 MAPI 后台处理程序传输交互上下文之外。 如果使用此标志调用 ValidateState ，则传输提供程序应执行以下操作：
设置内部状态标志以指示在调用 IXPLogon：：FlushQueues 方法时必须建立远程连接。
在状态表中设置正确的值，使 MAPI 后台处理程序启动队列刷新过程。
队列刷新完成后，释放共享资源。
清除 PR_STATUS_CODE 属性中的 STATUS_OFFLINE 位。
返回S_OK。
FORCE_XP_DISCONNECT
远程传输提供程序应释放其与消息传送系统资源的连接。 执行此操作后，它应在 PR_STATUS_CODE 属性中设置 STATUS_OFFLINE 位并返回S_OK。
PROCESS_XP_HEADER_CACHE
远程传输提供程序应处理远程消息并上传已延迟的任何消息。 为此，传输提供程序必须在登录对象的状态行中设置以下属性值：
将 PR_STATUS_STRING 属性设置为一个字符串，以向用户指示传输提供程序的状态。
在 PR_STATUS_CODE 属性中设置STATUS_OUTBOUND_ENABLED位和 STATUS_OUTBOUND_ACTIVE 位。
将传输提供程序的状态行中的 PR_REMOTE_VALIDATE_OK 属性设置为 FALSE。
如果另一个操作正在进行 (（例如在调用 ValidateState 时下载标头) ）， 则 ValidateState 应返回MAPI_E_BUSY。
执行用于处理 REFRESH_XP_HEADER_CACHE 标志的代码，以满足 Microsoft Exchange 客户端的要求。
REFRESH_XP_HEADER_CACHE
远程传输提供程序应从消息传递系统检索任何新的消息标头。 为此，传输提供程序必须执行以下操作：
将 PR_STATUS_STRING 属性设置为一个字符串，以向用户指示传输提供程序的状态。
在 PR_STATUS_CODE 属性中设置STATUS_INBOUND_ENABLED位和 STATUS_INBOUND_ACTIVE 位。
清除 PR_STATUS_CODE 属性中的 STATUS_OFFLINE 位。
在 PR_STATUS_CODE 属性中设置 STATUS_ONLINE 位。
将传输提供程序的状态行中的 PR_REMOTE_VALIDATE_OK 属性设置为 FALSE。
SHOW_XP_SESSION_UI
如果传输提供程序具有任何用于处理消息头 (的用户界面，例如确认) 下载消息的对话框，则应显示该对话框。 否则， ValidateState 可以返回MAPI_E_NO_SUPPORT。
如果传入除这些标志以外的任何标志， 则 ValidateState 应返回MAPI_E_UNKNOWN_FLAGS。
客户端对传输提供程序的调用通常是对 IMAPIStatus：：ValidateState 方法的调用。 在 处理 ValidateState 期间，传输提供程序不应执行任何分配稀缺系统资源的操作，例如调制解调器或 COM 端口。 这是因为 MAPI 后台处理程序有时需要在多个传输提供程序上刷新队列。 但是，客户端可以随时调用任何传输提供程序的 ValidateState 方法。 如果传输提供程序在 处理 ValidateState 期间尝试分配稀缺资源，则可能会由于与 MAPI 后台处理程序已指示刷新其队列的另一个传输提供程序冲突而导致错误。 如果允许在 MAPI 后台处理程序的指导下进行所有稀缺资源分配，则可以避免此类冲突。 传输提供程序应支持 PR_REMOTE_VALIDATE_OK 属性，以便客户端应用程序可以检测传输提供程序何时繁忙或等待 MAPI 后台处理程序启动操作。
给调用方的说明
由于此方法可能会导致进行其他可能较长的调用， 因此 ValidateState 可以返回MAPI_E_BUSY来通知你此方法正在等待另一个操作的完成。 在尝试另一个任务之前，应等到挂起的操作完成。
你对传输提供程序状态对象的调用拥有最大的控制权。 可以将一个或多个标志传递给 ValidateState ，这些标志会影响传输提供程序的操作。 例如，ABORT_XP_HEADER_OPERATION标志指示用户取消了验证。 传输提供程序可以决定中止、返回MAPI_E_USER_CANCELED，也可以继续。
可以在调用服务提供程序或 MAPI 后台处理程序的状态对象时设置CONFIG_CHANGED标志，以指示配置选项已更改。 可以使用CONFIG_CHANGED来动态重新配置传输提供程序。 在调用服务提供程序的状态对象时设置CONFIG_CHANGED时，提供程序会通过调用 IMAPISupport：：SpoolerNotify 来响应更改，以提醒 MAPI 后台处理程序更改。 在调用 MAPI 后台处理程序的状态对象时设置CONFIG_CHANGED时，后台处理程序会为每个活动传输提供程序调用 IXPLogon：：AddressTypes 。 AddressTypes 将传输支持的地址类型告知 MAPI 后台处理程序。 如果预计验证需要很长时间，某些服务提供商还会显示进度指示器。 显示进度指示器很有用，但不是必需的。
设置SUPPRESS_UI标志后，不能显示任何配置属性表或进度对话框。