Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 GetTickCountfunction.

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::MessagePendingafter 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::MessagePendingcall, it calculates the elapsed time since the original COM method call was made.

COM delivers the elapsed time in the dwTickCountparameter. 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 dwTickCountparameter — 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 threadIDCalleeparameter. 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::Reverton 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

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also