IMessageFilter::HandleInComingCall method

Provides a single entry point for incoming calls.

This method is called prior to each method invocation originating outside the current process and provides the ability to filter or reject incoming calls (or callbacks) to an object or a process.

Syntax


DWORD HandleInComingCall(
  [in]  DWORD dwCallType,
  [in]  HTASK htaskCaller,
  [in]  DWORD dwTickCount,
  [in]  LPINTERFACEINFO lpInterfaceInfo
);

Parameters

dwCallType [in]

The type of incoming call that has been received. Possible values are from the enumeration CALLTYPE.

htaskCaller [in]

The thread id of the caller.

dwTickCount [in]

The elapsed tick count since the outgoing call was made, if dwCallType is not CALLTYPE_TOPLEVEL. If dwCallType is CALLTYPE_TOPLEVEL, dwTickCount should be ignored.

lpInterfaceInfo [in]

A pointer to an INTERFACEINFO structure that identifies the object, interface, and method being called. In the case of DDE calls, lpInterfaceInfo can be NULL because the DDE layer does not return interface information.

Return value

This method can return the following values.

Return codeDescription
SERVERCALL_ISHANDLED

The application might be able to process the call.

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_RETRYLATER

The application cannot handle the call at this time. An application might return this value when it is in a user-controlled modal state.

 

Remarks

If implemented, HandleInComingCall is called by COM when an incoming COM message is received.

Depending on an application's current state, a call is either accepted and processed or rejected (permanently or temporarily). If SERVERCALL_ISHANDLED is returned, the application may be able to process the call, although success depends on the interface for which the call is destined. If the call cannot be processed, COM returns RPC_E_CALL_REJECTED.

Input-synchronized and asynchronous calls are dispatched even if the application returns SERVERCALL_REJECTED or SERVERCALL_RETRYLATER.

HandleInComingCall should not be used to hold off updates to objects during operations such as band printing. For that purpose, use IViewObject::Freeze.

You can also use HandleInComingCall to set up the application's state so that the call can be processed in the future.

Note  Although the htaskCaller parameter is typed as an HTASK, it contains the thread id of the calling thread. When you implement the IMessageFilter interface, you can call the OpenThread function to get the thread handle from the htaskCaller parameter, and you can call the GetProcessIdOfThread function to get the process id.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ObjIdl.h

IDL

ObjIdl.idl

IID

IID_IMessageFilter is defined as 00000016-0000-0000-C000-000000000046

See also

IMessageFilter

 

 

Community Additions

ADD
Show:
© 2014 Microsoft