com.jniwrapper.win32.com
Interface IMessageFilter

All Superinterfaces:

AutoDeleteParameter, IUnknown

All Known Implementing Classes:

IMessageFilterImpl

public interface IMessageFilter

extends IUnknown

Filtering messages helps to ensure that calls are handled in a manner that improves performance and avoids deadlocks. COM messages can be synchronous, asynchronous, or input-synchronized; the majority of interface calls are synchronous.

Synchronous calls require the caller to wait for a reply before continuing. COM enters a modal loop while waiting for the reply. During this time, the caller is still able to receive and dispatch incoming messages.

Field Summary

static java.lang.String

INTERFACE_IDENTIFIER

Method Summary

UInt32	handleInComingCall(UInt32 dwCallType, Pointer.Void htaskCaller, UInt32 dwTickCount, INTERFACEINFO lpInterfaceInfo) This method is an object-based method that provides the ability to filter or reject incoming calls (or call backs) to an object or a process.
UInt32	messagePending(Pointer.Void htaskCallee, UInt32 dwTickCount, UInt32 dwPendingType) 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.
UInt32	retryRejectedCall(Pointer.Void htaskCallee, UInt32 dwTickCount, UInt32 dwRejectType) This client-based method gives the application an opportunity to display a dialog box so the user can retry or cancel the call, or switch to the task identified by threadIDCallee.

Methods inherited from interface com.jniwrapper.win32.com.IUnknown

addRef, isNull, queryInterface, release, setNull

Methods inherited from interface com.jniwrapper.AutoDeleteParameter

isAutoDelete, setAutoDelete

Field Detail

INTERFACE_IDENTIFIER

public static final java.lang.String INTERFACE_IDENTIFIER

See Also:

Constant Field Values

Method Detail

handleInComingCall

public UInt32 handleInComingCall(UInt32 dwCallType,
                                 Pointer.Void htaskCaller,
                                 UInt32 dwTickCount,
                                 INTERFACEINFO lpInterfaceInfo)

This method is an object-based method that provides the ability to filter or reject incoming calls (or call backs) to an object or a process.

This method is called prior to each method invocation originating outside the current process.

Parameters:

dwCallType - Kind of incoming call that has been received. Valid values are from the enumeration CallType

htaskCaller - Handle of the task calling this task.

dwTickCount - Elapsed tick count since the outgoing call was made if dwCallType is not CallType.CALLTYPE_TOPLEVEL.

If dwCallType is CallType. CALLTYPE_TOPLEVEL, dwTickCount should be ignored.

lpInterfaceInfo - An INTERFACEINFO structure, which identifies the object, the interface, and the method making the call.

In the case of DDE calls, lpInterfaceInfo can be NULL because the DDE layer does not return interface information.

Returns:

ServerCall.SERVERCALL_ISHANDLED - The application might be able to process the call.

ServerCall.SERVERCALL_REJECTED - The application cannot handle the call due to an unforeseen problem, such as network unavailability, or if it is in the process of terminating.

ServerCall.SERVERCALL_RETRYLATER - The application cannot handle the call at this time. For example, an application might return this value when it is in a user-controlled modal state.

retryRejectedCall

public UInt32 retryRejectedCall(Pointer.Void htaskCallee,
                                UInt32 dwTickCount,
                                UInt32 dwRejectType)

This client-based method gives the application an opportunity to display a dialog box so the user can retry or cancel the call, or switch to the task identified by threadIDCallee.

Parameters:

htaskCallee - Handle of the server task that rejected the call.

dwTickCount - Number of elapsed ticks since the call was made.

dwRejectType - Specifies either ServerCall.SERVERCALL_REJECTED or ServerCall.SERVERCALL_RETRYLATER, as returned by the object application.

Returns:

-1: The call should be canceled. COM then returns RPC_E_CALL_REJECTED from the original method call.

Value >= 0 and <100: The call is to be retried immediately.

Value >= 100: COM will wait for this many milliseconds and then retry the call

messagePending

public UInt32 messagePending(Pointer.Void htaskCallee,
                             UInt32 dwTickCount,
                             UInt32 dwPendingType)

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.

Parameters:

htaskCallee - Task handle of the called application that has not yet responded.

dwTickCount - Number of ticks since the call was made.

dwPendingType - Type of call made during which a message or event was received.

Returns:

PENDINGMSG_CANCELCALL: Cancel the outgoing call.

PENDINGMSG_WAITNOPROCESS: Continue waiting for the reply and do not dispatch the message unless it is a task-switching or window-activation message.

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.