COleMessageFilter 类
管理 OLE 应用程序交互所需的并发。
语法
class COleMessageFilter : public CCmdTarget
成员
公共构造函数
| 名称 | 描述 |
|---|---|
| COleMessageFilter::COleMessageFilter | 构造 COleMessageFilter 对象。 |
公共方法
| 名称 | 描述 |
|---|---|
| COleMessageFilter::BeginBusyState | 使应用程序处于忙碌状态。 |
| COleMessageFilter::EnableBusyDialog | 启用和禁用在被调用的应用程序繁忙时出现的对话框。 |
| COleMessageFilter::EnableNotRespondingDialog | 启用和禁用在被调用的应用程序没有响应时出现的对话框。 |
| COleMessageFilter::EndBusyState | 终止应用程序的繁忙状态。 |
| COleMessageFilter::OnMessagePending | 由框架调用以在进行 OLE 调用时处理消息。 |
| COleMessageFilter::Register | 向 OLE 系统 DLL 注册消息筛选器。 |
| COleMessageFilter::Revoke | 调用向 OLE 系统 DLL 的消息筛选器注册。 |
| COleMessageFilter::SetBusyReply | 确定繁忙应用程序对 OLE 调用的回复。 |
| COleMessageFilter::SetMessagePendingDelay | 确定应用程序等待响应 OLE 调用的时间。 |
| COleMessageFilter::SetRetryReply | 确定调用应用程序对繁忙应用程序的回复。 |
备注
在可视化编辑服务器和容器应用程序中，以及在 OLE 自动化应用程序中，COleMessageFilter 类非常有用。 对于正在调用的服务器应用程序，可使用此类来使应用程序“忙碌”，这样以后就可取消或重试从其他容器应用程序传入的调用。 此类还可用于确定在被调用的应用程序繁忙时调用应用程序要执行的操作。
常见用途是，当销毁文档或其他可访问的 OLE 对象很危险时，供服务器应用程序来调用 BeginBusyState 和 EndBusyState。 这些调用是在用户界面更新期间在 CWinApp::OnIdle 中进行的。
默认情况下，初始化应用程序时会分配 COleMessageFilter 对象。 可使用 AfxOleGetMessageFilter 检索它。
这是一个高级类；你需要直接使用它的情况非常少。
有关详细信息，请参阅服务器：实现服务器一文。
继承层次结构
COleMessageFilter
要求
标头：afxole.h
COleMessageFilter::BeginBusyState
调用此函数可开始忙碌状态。
virtual void BeginBusyState();
备注
它与 EndBusyState 结合使用来控制应用程序的繁忙状态。 SetBusyReply 函数确定应用程序在繁忙时对调用应用程序的回复。
BeginBusyState 和 EndBusyState 分别调用递增和递减计数器，用于确定应用程序是否繁忙。 例如，调用 BeginBusyState 两次和调用 EndBusyState 一次仍会导致繁忙状态。 若要取消忙碌状态，必须调用 EndBusyState，调用次数与调用 BeginBusyState 的次数相同。
默认情况下，框架在空闲处理期间进入忙碌状态，该处理由 CWinApp::OnIdle 执行。 当应用程序处理 ON_COMMANDUPDATEUI 通知时，会稍后再处理传入的调用，即在空闲处理完成后进行处理。
COleMessageFilter::COleMessageFilter
创建一个 COleMessageFilter 对象。
COleMessageFilter();
COleMessageFilter::EnableBusyDialog
启用和禁用“忙碌”对话框，在 OLE 调用期间消息挂起延迟过期时，会显示此对话框（请参阅 SetRetryReply）。
void EnableBusyDialog(BOOL bEnableBusy = TRUE);
参数
bEnableBusy
指定是启用还是禁用“忙碌”对话框。
COleMessageFilter::EnableNotRespondingDialog
启用和禁用“未响应”对话框。如果键盘或鼠标消息在 OLE 调用期间挂起且调用超时，会显示该对话框。
void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);
参数
bEnableNotResponding
指定是启用还是禁用“未响应”对话框。
COleMessageFilter::EndBusyState
调用此函数可结束忙碌状态。
virtual void EndBusyState();
备注
它与 BeginBusyState 结合使用来控制应用程序的繁忙状态。 SetBusyReply 函数确定应用程序在繁忙时对调用应用程序的回复。
BeginBusyState 和 EndBusyState 分别调用递增和递减计数器，用于确定应用程序是否繁忙。 例如，调用 BeginBusyState 两次和调用 EndBusyState 一次仍会导致繁忙状态。 若要取消忙碌状态，必须调用 EndBusyState，调用次数与调用 BeginBusyState 的次数相同。
默认情况下，框架在空闲处理期间进入忙碌状态，该处理由 CWinApp::OnIdle 执行。 当应用程序处理 ON_UPDATE_COMMAND_UI 通知时，会在空闲处理完成后处理传入的调用。
COleMessageFilter::OnMessagePending
由框架调用以在进行 OLE 调用时处理消息。
virtual BOOL OnMessagePending(const MSG* pMsg);
参数
pMsg
指向挂起的消息的指针。
返回值
若成功，则为非零；否则为 0。
备注
当调用应用程序等待调用完成时，框架会调用 OnMessagePending 并显示指向挂起的消息的指针。 默认情况下，框架会调度 WM_PAINT 消息，这样就可在长时间调用期间发生窗口更新。
必须先通过调用 Register 来注册消息筛选器，然后该筛选器才能处于活动状态。
COleMessageFilter::Register
向 OLE 系统 DLL 注册消息筛选器。
BOOL Register();
返回值
若成功，则为非零；否则为 0。
备注
除非向系统 DLL 注册消息筛选器，否则该消息筛选器不起作用。 通常，应用程序的初始化代码会注册应用程序的消息筛选器。 在程序通过调用 Revoke 终止之前，应撤销应用程序注册的任何其他消息筛选器。
框架的默认消息筛选器在初始化期间自动注册，在终止时自动撤销。
COleMessageFilter::Revoke
撤销通过调用 Register 指定的先前注册。
void Revoke();
注解
应在程序终止之前撤销消息筛选器。
由框架自动创建和注册的默认消息筛选器也会自动撤销。
COleMessageFilter::SetBusyReply
此函数设置应用程序的“忙回复”。
void SetBusyReply(SERVERCALL nBusyReply);
参数
nBusyReply
SERVERCALL 枚举中的值，定义见 COMPOBJ.H。 它可以具有以下任一值：
SERVERCALL_ISHANDLED：应用程序可接受调用，但在处理特定调用时可能会失败。
SERVERCALL_REJECTED：应用程序可能永远无法处理调用。
SERVERCALL_RETRYLATER：应用程序暂时处于无法处理调用的状态。
备注
BeginBusyState 和 EndBusyState 函数可控制应用程序的繁忙状态。
当应用程序通过调用 BeginBusyState 而变得繁忙时，它会响应来自 OLE 系统 DLL 的调用，其值由 SetBusyReply 的最后一个设置确定。 调用应用程序使用此忙回复来确定要执行的操作。
默认情况下，忙回复是 SERVERCALL_RETRYLATER。 此回复会导致调用应用程序尽快重试呼叫。
COleMessageFilter::SetMessagePendingDelay
确定调用应用程序在采取进一步操作之前等待被调用的应用程序响应的时间。
void SetMessagePendingDelay(DWORD nTimeout = 5000);
参数
nTimeout
消息挂起延迟的毫秒数。
备注
此函数与 SetRetryReply 协同工作。
COleMessageFilter::SetRetryReply
确定调用应用程序在从被调用的应用程序接收繁忙响应时的操作。
void SetRetryReply(DWORD nRetryReply = 0);
参数
nRetryReply
重试之间的毫秒数。
备注
当被调用的应用程序指示它正忙时，调用应用程序可能会决定等到服务器不再忙，立即重试，或者在指定的时间间隔后再重试。 它还可能决定完全取消调用。
调用方的响应由函数 SetRetryReply 和 SetMessagePendingDelay 控制。 SetRetryReply 确定调用应用程序在重试给定调用之间应等待的时间。 SetMessagePendingDelay 确定调用应用程序在采取进一步操作之前等待服务器响应的时间。
通常，默认值是可接受的，不需要更改。 框架每 nRetryReply 毫秒重试一次调用，直到调用通过或消息挂起延迟已过期。 如果 nRetryReply 的值为 0，则指定立即重试；如果为 1，则指定取消调用。
消息挂起延迟过期后，将显示 OLE“忙碌对话框”（请参阅 COleBusyDialog），以便用户可选择取消或重试调用。 调用 EnableBusyDialog 可启用或禁用此对话框。
如果键盘或鼠标消息在调用期间挂起，并且调用超时（超过消息挂起延迟），则会显示“未响应”对话框。 调用 EnableNotRespondingDialog 可启用或禁用此对话框。 通常，这种情况表明出现问题，且用户开始不耐烦了。
禁用对话框后，当前“重试回复”始终用于对繁忙应用程序的调用。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈