C O le M essageFilter

COleMessageFilter 类 管 理 OLE 应 用 程 序 交 互 所 需 要 的 并 行 能 力 。

COleMessageFilter 类 用 于 可 视 化 编 辑 服 务 器 和 容 器 应 用 程 序 中 ， 以 及 OLE 自动 化 应 用 程 序 中 。 对 于 要 调 用 的 服 务 器 应 用 程 序 ， 该 类 可 使 应 用 程 序 保 持 “ 忙 ”

的 状 态 ， 这 样 其 他 容 器 应 用 程 序 的 调 用 请 求 就 会 被 取 消 或 稍 后 重 试 。 当 被 调 用的 应 用 程 序 忙 时 ， 也 可 以 使 用 该 类 确 定 调 用 者 应 用 程 序 将 采 取 什 么 样 的 动 作 。

服 务 器 应 用 程 序 常 用 的 用 法 是 在 文 档 或 其 他 OLE 可 访 问 的 对 象 有 可 能 遭 到 破坏 的 情 况 下 调 用 BeginBusyState 和 EndBusyState 。 在 用 户 界 面 更 新 过 程 中 ， C W inApp::OnIdle 将 发 起 这 些 调 用 。

缺 省 地 ， 当 应 用 程 序 初 始 化 时 就 分 配 一 个 COleMessageFilter 对 象 。 可 以 使 用AfxOleGetMessageFilter 检 索 该 对 象 。

这 是 一 个 高 级 类 ； 你 很 少 需 要 直 接 使 用 该 类 。

要 获 得 更 详 细 的 信 息 ， 请 参 阅 “ Visual C++ 程 序 员 指 南 ” 在 线 文 档 中 的 “ 服 务器 ： 实 施 一 个 服 务 器 ” 一 节 。

#include <afxole.h>

请 参 阅 CCmdTarget

CO le M essageFilter 类 成 员

构 造 器

ColeMessageFilter 构 造 一 个 COleMessageFilter 对 象

操 作

Register 注 册 OLE 系 统 DLL 的 消 息 过 滤 器

Revoke 激 活 OLE 系 统 DLL 消 息 过 滤 器 的 注 册 过 程

BeginBusyState 使 应 用 程 序 处 于 忙 的 状 态

EndBusyState 结 束 应 用 程 序 忙 的 状 态

SetBusyReply 确 定 忙 的 应 用 程 序 对 OLE 调 用 的 回 答

SetRetryReply 确 定 调 用 者 应 用 程 序 对 忙 应 用 程 序 的 回 答

SetMessagePendingDelay 确 定 应 用 程 序 要 等 多 长 时 间 才 对 OLE 调 用 做 出

响 应

EnableBusyDialog 使 能 或 禁 止 在 被 调 用 的 应 用 程 序 处 于 忙 状 态 时

所 显 示 的 对 话 框

EnableNotRespondingDialo g

续 表

使 能 或 禁 止 在 被 调 用 的 应 用 程 序 没 有 响 应 时 所显 示 的 对 话 框

重 载

OnMessagePending 在 处 理 OLE 调 用 时 框 架 调 用 该 方 法 处 理 消 息

成 员 函 数

CO leMessageFilter::BeginBusyState

virtual void BeginBusySystem();

说 明

调 用 该 函 数 将 启 动 忙 状 态 。 其 与 EndBusyState 函 数 一 起 控 制 应 用 程 序 忙 的 状

态 。

SetBusyReply 方 法 确 定 在 应 用 程 序 忙 时 对 调 用 者 应 用 程 序 所 做 的 响 应 。

BeginBusyState 和 EndBusyState 分 别 增 加 或 减 少 用 于 决 定 应 用 程 序 忙 状 态 的 计数 器 。 例 如 ，

调 用 BeginBusyState 两 次 和 调 用 EndBusyState 一 次 将 导 致 忙 状 态 。 要 取 消 忙状 态 ， 调 用 EndBusyState 的 次 数 与 调 用 BeginBusyState 的 次 数 必 须 相 等 。

缺 省 地 ， 框 架 在 空 闲 处 理 过 程 中 进 入 忙 状 态 ， 这 是 由 C W inApp::OnIdle 来 执 行的 。 当 应 用 程 序 正 在 处 理 ON_COMMANDUPDATEUI 通 知 时 ， 发 来 的 调 用 请求 将 稍 后 处 理 ， 要 等 到 空 闲 处 理 过 程 完 成 之 后 。

请 参 阅 COleMessageFilter::EndBusyState, COleMessageFilter::SetBusyState, CWinApp::OnIdle

CO leMessageFilter::COleMessageFilter

COleMessageFilter() ;

说 明

创 建 一 个 COleMessageFilter 对 象 。

请 参 阅 COleMessageFilter::Register, COleMessageFilter::Remove 。

CO leMessageFilter::EnableBusyDialog

void EnableBusyDialog ( BOOL bEnableBusy = TRUE );

参 数

bEnableBusy

指 明 “ 忙 ” 对 话 框 是 使 能 还 是 禁 止 。

使 能 或 禁 止 忙 对 话 框 ， 在 OLE 调 用 过 程 中 当 发 送 消 息 逾 期 而 没 有 回 应 时 （ 请参 阅 SetRetry - Reply ） ， 将 显 示 该 对 话 框 。

请 参 阅 COleMessageFilter::EnableNotRespondingDialog,

COleMessageFilter::BeginBusyState, COleMessageFilter::SetBusyReply, COleMessageFilter::SetRetryReply, COleBusyDialog

CO leMessageFilter::EnableNotRespondingDialog

void EnableNotRespondingDialog ( BOOL bEnableNotResponding = TRUE )

参 数

bEnableNotResponding

指 明 “ 无 响 应 ” 对 话 框 是 使 能 还 是 禁 止 。

使 能 或 禁 止 “ 无 响 应 ” 对 话 框 ， 在 OLE 调 用 过 程 中 发 送 键 盘 或 鼠 标 消 息 而 该调 用 过 程 超 时 就 显 示 该 对 话 框 。

请 参 阅 COleMessageFilter::EnableBusyDialog,

COleMessageFilter::BeginBusyState,COleMessageFilter::SetBusyReply, COleBusyDialog

CO leMessageFilter::EndBusyState

virtual void EndBusyState () ;

说 明

调 用 该 函 数 结 束 忙 状 态 。 其 与 BeginBusyState 函 数 一 起 控 制 应 用 程 序 忙 的 状 态 。函 数 SetBusyReply 决 定 在 其 处 于 忙 状 态 时 对 调 用 者 应 用 程 序 的 响 应 。

BeginBusyState 和 EndBusyState 分 别 增 加 或 减 少 用 于 决 定 应 用 程 序 忙 状 态 的 计数器。例如，调用 BeginBusyState 两 次 和 调 用 EndBusyState 一 次 将 导 致 忙 状 态 。要 取 消 忙 状 态 ， 调 用

EndBusyState 的 次 数 与 调 用 BeginBusyState 的 次 数 必 须 相 等 。

缺 省 地 ， 框 架 在 空 闲 处 理 过 程 中 进 入 忙 状 态 ， 这 是 由 C W inApp::OnIdle 来 执 行的 。 当 应 用 程 序 正 在 处 理 ON_UPDATE_COMMAND_UI 通 知 时 ， 发 来 的 调 用请 求 将 稍 后 处 理 ， 要 等 到 空 闲 处 理 过 程 完 成 之 后 。

请 参 阅 COleMessageFilter::BeginBusyState, COleMessageFilter::SetBusyState, CWinApp::OnIdle

CO leMessageFilter::OnMessagePending

virtual BOOL OnMessagePending ( const MSG* pMsg );

返 回 值

非 0 代 表 成 功 ； 否 则 ， 就 返 回 0 。

参 数

pMsg

要 发 送 消 息 的 指 针 。

说 明

在 OLE 调 用 过 程 中 框 架 调 用 该 函 数 处 理 消 息 。

当 调 用 者 应 用 程 序 在 等 待 调 用 完 成 时 ， 框 架 就 调 用 OnMessagePending 方 法 ， 其 参 数 是 一 个 指 向 要 发 送 消 息 的 制 止 。 缺 省 地 ， 框 架 发 送 WM_PAINT 消 息 ， 因 此 在 一 个 花 费 很 长 时 间 的 调 用 过 程 中 出 口 仍 可 以 更 新 。

请 参 阅 COleMessageFilter::Register, AfxOleInit, CWinApp::InitInstance

CO leMessageFilter::Register

BOOL Register ();

返 回 值

非 0 代 表 成 功 ； 否 则 ， 就 返 回 0 。

说 明

该 函 数 注 册 OLE 系 统 DLL 的 消 息 过 滤 器 。 一 个 消 息 过 滤 器 不 起 作 用 ， 除 非 向系 统 DLL 进 行 注 册 。 通 常 ， 你 在 应 用 程 序 初 始 化 代 码 中 注 册 应 用 程 序 的 消 息过 滤 器 。 你 的 应 用 程 序 所 注 册 的 任 何 消 息 过 滤 器 在 应 用 程 序 终 止 之 前 都 应 调 用

框 架 缺 省 的 消 息 过 滤 器 在 初 始 化 时 自 动 进 行 了 注 册 ， 并 在 终 止 之 前 自 动 撤 销 。

请 参 阅 COleMessageFilter::Revoke

CO leMessageFilter::Revoke

void Revoke () ;

说 明

撤 销 以 前 调 用 Register 所 注 册 的 信 息 。 在 应 用 程 序 终 止 之 前 应 撤 销 消 息 过 滤 器 。由 框 架 自 动 创 建 和 注 册 的 缺 省 消 息 过 滤 器 也 将 自 动 被 撤 销 。

请 参 阅 COleMessageFilter::Register

CO leMessageFilter::SetBusyReply

void SetBusyReply ( SERVERCALL nBusyReply )

参 数

nBusyReply

SERVERCALL 枚 举 集 合 中 的 一 个 值 ， 在 COMPOBJ.H 文 件 中 定 义 。 可以 是 下 面 的 一 个 值 ：

• SERVERCALL_ISHANDLED 应 用 程 序 可 以 接 受 调 用 ， 但 在 处 理

  某 些特 殊 的 调 用 过 程 中 可 能 会 失 败 。

• SERVERCALL_REJECTED 应 用 程 序 可 能 永 远 都 不 会 处 理 该 调 用

  。

• SERVERCALL_RETRYLATER 应 用 程 序 处 于 暂 时 不 能 处 理 调 用 的

  状态 中 。

说 明

该 函 数 将 应 用 程 序 设 置 为 “忙 - 响 应 ” 状 态 。 BeginBusyState 和 EndBusyState 函数 控 制 着 应 用 程 序 忙 的 状 态 。

当 调 用 BeginBusyState 函 数 将 应 用 程 序 设 置 为 忙 状 态 时 ， 其 对 来 自 OLE 系 统

DLL 调 用 的

响 应 值 是 由 最 近 调 用 SetBusyReply 函 数 的 设 置 值 所 决 定 的 。 调 用 者 应 用 程 序使 用 该 忙 - 响 应 信 息 决 定 采 取 什 么 动 作 。

缺 省 地 ， 忙 － 响 应 是 SERVERCALL_RETRYLATER 。 该 响 应 消 息 导 致 调 用 者应 用 程 序 尽 快 重 试 该 调 用 过 程 。

请 参 阅 COleMessageFilter::BeginBusyState, COleMessageFilter::EndBusyState

CO leMessageFilter::SetMessagePendingDelay

void SetMessagePendingDelay ( D WORD nTimeout = 5000 ) ;

参 数

nTimeout

消 息 延 迟 发 送 的 秒 数 。

说 明

该 函 数 决 定 在 调 用 者 应 用 程 序 将 在 多 长 时 间 内 等 待 被 调 用 应 用 程 序 的 响 应 ， 过了 该 时 间 ，

调 用 者 应 用 程 序 将 采 取 进 一 步 的 动 作 。该 函 数 与 SetRetryRelay 函 数 协 同 工 作 。

请 参 阅 COleMessageFilter::SetRetryReply

CO leMessageFilter::SetRetryReply

void SetRetryReply ( DWORD nRetryReply = 0 ) ;

参 数

nRetryReply

两 次 重 试 之 间 所 等 待 的 秒 数 。

说 明

该 函 数 将 决 定 调 用 者 应 用 程 序 在 收 到 被 调 用 应 用 程 序 的 忙 响 应 信 息 时 所 采 取 的动 作 。

当 被 调 用 的 应 用 程 序 指 明 自 己 忙 时 ， 调 用 者 应 用 程 序 可 能 会 决 定 等 待 直 到 服 务器 不 再 忙 、 立 刻 重 试 或 在 指 定 的 间 隔 后 重 试 。 也 可 能 决 定 取 消 本 次 调 用 。

调 用 者 的 响 应 是 由 SetRetryReply 和 SetMessagePendingDelay 控 制 的 。

SetRetryReply 决 定 调 用 者 应 用 程 序 在 重 试 调 用 时 应 等 待 多 长 时 间 。SetMessagePendingDelay 决 定 调 用 者 应 用 程 序 在 采 取 进 一 步 动 作 之 前 等 待 服 务器 做 出 响 应 的 时 间 。

通 常 ， 缺 省 值 都 是 可 接 受 的 ， 不 需 要 修 改 。 框 架 将 每 隔 nRetryRelay 毫 秒 就 重试 调 用 ， 直 到 调 用 成 功 或 者 超 出 了 消 息 发 送 延 迟 时 间 规 定 。 nRetryRelay 取 0 值则 意 味 着 立 即 重 试 ， -1 则 意 味 着 取 消 本 次 调 用 。

当 超 出 消 息 延 迟 发 送 时 间 限 制 时 ， 就 显 示 OLE “ 忙 - 对 话 框 ” ， 这 样 用 户 就 可 以选 择 是 取

消 本 次 调 用 还 是 重 试 。 调 用 EnableBusyDialog 函 数 来 使 能 或 禁 止 该 对 话 框 。

当 在 调 用 过 程 中 发 送 键 盘 或 鼠 标 消 息 而 调 用 超 时 时 （ 超 出 了 消 息 发 送 延 迟 规定 ） ， 就 显 示 “ 无 响 应 ” 对 话 框 。 调 用 EnableNotRespondingDialog 来 使 能 或 禁止 该 对 话 框 。 通 常 ， 这 种 状 态 意 味 着 某 些 东 西 出 现 了 错 误 ， 用 户 已 经 不 耐 烦 了 。

当 禁 止 该 对 话 框 时 ， 对 于 调 用 处 于 忙 状 态 的 应 用 程 序 总 是 使 用 当 前 “ 重 试 响应 ” 。

请 参 阅 COleBusyDialog, COleMessageFilter::EnableNotRespondingDialog,

COleMessageFilter::EnableBusyDialog, COleMessageFilter::SetMessagePendingDelay