IMessageFilter::MessagePending

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This client-based method is called by COM when a Windows message appears in a COM 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.

Syntax

DWORD MessagePending(
  HTASK threadIDCallee,
  DWORD dwTickCount,
  DWORD dwPendingType 
);

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 Value

• 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.

  COM 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 as per usual, if the outgoing call is completed.

  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.

  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

COM calls IMessageFilter::MessagePending after an application has made a COM 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 COM makes the IMessageFilter::MessagePending call, it calculates the elapsed time since the original COM method call was made.

COM delivers the elapsed time in the dwTickCount parameter. In the meantime, COM 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 the following:

• 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 can 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 COM call, the application can cancel the call and restore the COM 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.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

See Also

Reference

IStorage::Revert