COleMessageFilter Class
Manages the concurrency required by the interaction of OLE applications.
Syntax
class COleMessageFilter : public CCmdTarget
Members
Public Constructors
| Name | Description |
|---|---|
| COleMessageFilter::COleMessageFilter | Constructs a COleMessageFilter object. |
Public Methods
| Name | Description |
|---|---|
| COleMessageFilter::BeginBusyState | Puts the application in the busy state. |
| COleMessageFilter::EnableBusyDialog | Enables and disables the dialog box that appears when a called application is busy. |
| COleMessageFilter::EnableNotRespondingDialog | Enables and disables the dialog box that appears when a called application is not responding. |
| COleMessageFilter::EndBusyState | Terminates the application's busy state. |
| COleMessageFilter::OnMessagePending | Called by the framework to process messages while an OLE call is in progress. |
| COleMessageFilter::Register | Registers the message filter with the OLE system DLLs. |
| COleMessageFilter::Revoke | Revokes the message filter's registration with the OLE system DLLs. |
| COleMessageFilter::SetBusyReply | Determines the busy application's reply to an OLE call. |
| COleMessageFilter::SetMessagePendingDelay | Determines how long the application waits for a response to an OLE call. |
| COleMessageFilter::SetRetryReply | Determines the calling application's reply to a busy application. |
Remarks
The COleMessageFilter class is useful in visual editing server and container applications, as well as OLE automation applications. For server applications that are being called, this class can be used to make the application "busy" so that incoming calls from other container applications are either canceled or retried later. This class can also be used to determine the action to be taken by a calling application when the called application is busy.
Common usage is for a server application to call BeginBusyState and EndBusyState when it would be dangerous for a document or other OLE accessible object to be destroyed. These calls are made in CWinApp::OnIdle during user-interface updates.
By default, a COleMessageFilter object is allocated when the application is initialized. It can be retrieved with AfxOleGetMessageFilter.
This is an advanced class; you seldom need to work with it directly.
For more information, see the article Servers: Implementing a Server.
Inheritance Hierarchy
COleMessageFilter
Requirements
Header: afxole.h
COleMessageFilter::BeginBusyState
Call this function to begin a busy state.
virtual void BeginBusyState();
Remarks
It works in conjunction with EndBusyState to control the application's busy state. The function SetBusyReply determines the application's reply to calling applications when it is busy.
The BeginBusyState and EndBusyState calls increment and decrement, respectively, a counter that determines whether the application is busy. For example, two calls to BeginBusyState and one call to EndBusyState still result in a busy state. To cancel a busy state it is necessary to call EndBusyState the same number of times BeginBusyState has been called.
By default, the framework enters the busy state during idle processing, which is performed by CWinApp::OnIdle. While the application is handling ON_COMMANDUPDATEUI notifications, incoming calls are handled later, after idle processing is complete.
COleMessageFilter::COleMessageFilter
Creates a COleMessageFilter object.
COleMessageFilter();
COleMessageFilter::EnableBusyDialog
Enables and disables the busy dialog box, which is displayed when the message-pending delay expires (see SetRetryReply) during an OLE call.
void EnableBusyDialog(BOOL bEnableBusy = TRUE);
Parameters
bEnableBusy
Specifies whether the "busy" dialog box is enabled or disabled.
COleMessageFilter::EnableNotRespondingDialog
Enables and disables the "not responding" dialog box, which is displayed if a keyboard or mouse message is pending during an OLE call and the call has timed out.
void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);
Parameters
bEnableNotResponding
Specifies whether the "not responding" dialog box is enabled or disabled.
COleMessageFilter::EndBusyState
Call this function to end a busy state.
virtual void EndBusyState();
Remarks
It works in conjunction with BeginBusyState to control the application's busy state. The function SetBusyReply determines the application's reply to calling applications when it is busy.
The BeginBusyState and EndBusyState calls increment and decrement, respectively, a counter that determines whether the application is busy. For example, two calls to BeginBusyState and one call to EndBusyState still result in a busy state. To cancel a busy state it is necessary to call EndBusyState the same number of times BeginBusyState has been called.
By default, the framework enters the busy state during idle processing, which is performed by CWinApp::OnIdle. While the application is handling ON_UPDATE_COMMAND_UI notifications, incoming calls are handled after idle processing is complete.
COleMessageFilter::OnMessagePending
Called by the framework to process messages while an OLE call is in progress.
virtual BOOL OnMessagePending(const MSG* pMsg);
Parameters
pMsg
Pointer to the pending message.
Return Value
Nonzero on success; otherwise 0.
Remarks
When a calling application is waiting for a call to be completed, the framework calls OnMessagePending with a pointer to the pending message. By default, the framework dispatches WM_PAINT messages, so that window updates can occur during a call that is taking a long time.
You must register your message filter by means of a call to Register before it can become active.
COleMessageFilter::Register
Registers the message filter with the OLE system DLLs.
BOOL Register();
Return Value
Nonzero on success; otherwise 0.
Remarks
A message filter has no effect unless it is registered with the system DLLs. Usually your application's initialization code registers the application's message filter. Any other message filter registered by your application should be revoked before the program terminates by a call to Revoke.
The framework's default message filter is automatically registered during initialization and revoked at termination.
COleMessageFilter::Revoke
Revokes a previous registration performed by a call to Register.
void Revoke();
Remarks
A message filter should be revoked before the program terminates.
The default message filter, which is created and registered automatically by the framework, is also automatically revoked.
COleMessageFilter::SetBusyReply
This function sets the application's "busy reply."
void SetBusyReply(SERVERCALL nBusyReply);
Parameters
nBusyReply
A value from the SERVERCALL enumeration, which is defined in COMPOBJ.H. It can have any one of the following values:
SERVERCALL_ISHANDLED The application can accept calls but may fail in processing a particular call.
SERVERCALL_REJECTED The application probably will never be able to process a call.
SERVERCALL_RETRYLATER The application is temporarily in a state in which it cannot process a call.
Remarks
The BeginBusyState and EndBusyState functions control the application's busy state.
When an application has been made busy with a call to BeginBusyState, it responds to calls from the OLE system DLLs with a value determined by the last setting of SetBusyReply. The calling application uses this busy reply to determine what action to take.
By default, the busy reply is SERVERCALL_RETRYLATER. This reply causes the calling application to retry the call as soon as possible.
COleMessageFilter::SetMessagePendingDelay
Determines how long the calling application waits for a response from the called application before taking further action.
void SetMessagePendingDelay(DWORD nTimeout = 5000);
Parameters
nTimeout
Number of milliseconds for the message-pending delay.
Remarks
This function works in concert with SetRetryReply.
COleMessageFilter::SetRetryReply
Determines the calling application's action when it receives a busy response from a called application.
void SetRetryReply(DWORD nRetryReply = 0);
Parameters
nRetryReply
Number of milliseconds between retries.
Remarks
When a called application indicates that it is busy, the calling application may decide to wait until the server is no longer busy, to retry right away, or to retry after a specified interval. It may also decide to cancel the call altogether.
The caller's response is controlled by the functions SetRetryReply and SetMessagePendingDelay. SetRetryReply determines how long the calling application should wait between retries for a given call. SetMessagePendingDelay determines how long the calling application waits for a response from the server before taking further action.
Usually the defaults are acceptable and do not need to be changed. The framework retries the call every nRetryReply milliseconds until the call goes through or the message-pending delay has expired. A value of 0 for nRetryReply specifies an immediate retry, and - 1 specifies cancellation of the call.
When the message-pending delay has expired, the OLE "busy dialog box" (see COleBusyDialog) is displayed so that the user can choose to cancel or retry the call. Call EnableBusyDialog to enable or disable this dialog box.
When a keyboard or mouse message is pending during a call and the call has timed out (exceeded the message-pending delay), the "not responding" dialog box is displayed. Call EnableNotRespondingDialog to enable or disable this dialog box. Usually this state of affairs indicates that something has gone wrong and the user is getting impatient.
When the dialogs are disabled, the current "retry reply" is always used for calls to busy applications.