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.
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. |
INTERFACE_IDENTIFIER
public static final java.lang.String INTERFACE_IDENTIFIER
- See Also:
- Constant Field Values
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.