IMessageFilter::MessagePending
A
client-based method called by COM when a Windows message appears in an OLE
application s message queue while the application is waiting for a reply to a
remote call. Handling input while waiting for an outgoing call to finish can
introduce complications. The application should determine whether to process
the message without interrupting the call, continue waiting, or cancel the
operation.
DWORD MessagePending(
|
HTASK threadIDCallee, |
//Called applications task handle |
|
DWORD dwTickCount, |
//Elapsed tick count |
|
DWORD dwPendingType |
//Call type |
|
); |
|
Parameters
threadIDCallee
[in] Task
handle of the called application that has not yet responded.
dwTickCount
[in] Number
of ticks since the call was made. It is calculated from the Windows GetTickCount
function.
dwPendingType
[in] Type of
call made during which a message or event was received. Valid values are from
the enumeration PENDINGTYPE
(where PENDINGTYPE_TOPLEVEL means the outgoing call was not nested within a
call from another application and PENDINTGYPE_NESTED means the outgoing call
was nested within a call from another application).
Return Values
PENDINGMSG_CANCELCALL
Cancel the
outgoing call. This should be returned only under extreme conditions. Canceling
a call that has not replied or been rejected can create orphan transactions and
lose resources. OLE fails the original call and returns RPC_E_CALL_CANCELLED.
PENDINGMSG_WAITNOPROCESS
Continue waiting
for the reply and do not dispatch the message unless it is a task-switching or
window-activation message. A subsequent message will trigger another call to IMessageFilter::MessagePending.
Leaving messages or events in the queue enables them to be processed normally,
if the outgoing call is completed. Note that returning PENDINGMSG_WAITNOPROCESS
can cause the message queue to fill.
PENDINGMSG_WAITDEFPROCESS
Because of
the increased resources available in 32-bit systems, you are unlikely to get
this return value. It now indicates the same state as PENDINGMSG_WAITNOPROCESS.
Keyboard and
mouse messages are no longer dispatched, as was done with PENDINGMSG_WAITDEFPROCESS.
However there are some cases where mouse and keyboard messages could cause the
system to deadlock, and in these cases, mouse and keyboard messages are
discarded. WM_PAINT messages are dispatched. Task-switching and activation
messages are handled as before.
Remarks
OLE calls IMessageFilter::MessagePending
after an application has made an OLE method call and a Windows message occurs
before the call has returned. A Windows message is sent, for example, when the
user selects a menu command or double-clicks an object. Before OLE makes the IMessageFilter::MessagePending
call, it calculates the elapsed time since the original OLE method call was
made. OLE delivers the elapsed time in the dwTickCount parameter. In the
meantime, OLE does not remove the message from the queue.
Windows
messages that appear in the caller s queue should remain in the queue until
sufficient time has passed to ensure that the messages are probably not the
result of typing ahead, but are, instead, an attempt to get attention. Set the
delay with the dwTickCount parameter a two- or three-second delay is recommended. If that amount of time
passes and the call has not been completed, the caller should flush the
messages from the queue, and the OLE UI busy dialog box should be displayed
offering the user the choice of retrying the call (continue waiting) or
switching to the task identified by the threadIDCallee parameter. This
ensures that:
If calls are completed in a
reasonable amount of time, type ahead will be treated correctly.
If the callee does not respond,
type ahead is not misinterpreted and the user is able to act to solve the
problem. For example, OLE 1 servers can queue up requests without responding
when they are in modal dialog boxes.
Handling
input while waiting for an outgoing call to finish can introduce complications.
The application should determine whether to process the message without
interrupting the call, continue waiting, or cancel the operation.
When
there is no response to the original OLE call, the application can cancel the
call and restore the OLE object to a consistent state by calling IStorage::Revert on its storage. The object
can be released when the container can shut down. However, canceling a call can
create orphaned operations and resource leaks. Canceling should be used only
as a last resort. It is strongly recommended that applications not allow such
calls to be canceled.
See Also