DllDebugObjectRPCHook

BOOL WINAPI DllDebugObjectRPCHook(BOOL fTrace, LPORPC_INIT_ARGS lpOrpcInitArgs)

This function is to be exported by name from one or more .DLLs that wish to be informed when, from the user's point of view, debugging is engaged. Debuggers should call this function to inform each of their loaded .DLLs that export this function as to whether they are presently being debugged or not. When the debugger wants to enable debugging, it calls DllDebugObjectRpcHook with fTrace=TRUE and when it wants to disable it, it calls DllDebugObjectRpcHook with fTrace=FALSE. When enabled, debugging support such as the tracing described herein should be enabled.

Certain of the COM Library .DLLs, for example, implement this function. When debugging is enabled, they turn on what is here called COM remote debugging, and which is the focus of this section.

The second argument points to an ORPC_INIT_ARGS structure whose definition is given below. The pvPSN member is used only on the Apple Macintosh platform, where the calling debugger is required in this field to pass the process serial number of the debuggee's process. On other systems pvPSN should be NULL.

The lpIntfOrpcDebug member is a pointer to an interface. This is used by in-process debuggers and is discussed in more detail later. Debuggers that are neither in-process debuggers nor are Macintosh debuggers should pass NULL for lpIntfOrpcDebug.

typedef struct ORPC_INIT_ARGS {
   IOrpcDebugNotify __RPC_FAR *    lpIntfOrpcDebug;
   void *                  pvPSN;         // contains ptr to Process Serial No. for Mac COM debugging.
   DWORD                  dwReserved1;    // For future use, must be 0.
   DWORD                  dwReserved2;    // For future use, must be 0.
   } ORPC_INIT_ARGS;
   
typedef ORPC_INIT_ARGS  __RPC_FAR * LPORPC_INIT_ARGS;

interface IOrpcDebugNotify : IUnknown {
   VOID   ClientGetBufferSize(LPORPC_DBG_ALL);
   VOID   ClientFillBuffer(LPORPC_DBG_ALL);
   VOID   ClientNotify(LPORPC_DBG_ALL);
   VOID    ServerNotify(LPORPC_DBG_ALL);
   VOID   ServerGetBufferSize(LPORPC_DBG_ALL);
   VOID   ServerFillBuffer(LPORPC_DBG_ALL);
   };

As one would expect, a debugger calls DllDebugObjectRPCHook within the context (that is, within the process) of the relevant debuggee. Thus, the implementation of this function most often will merely store the arguments in global .DLL-specific state.

Further, as this function is called from the debugger, the function can be called when the .DLL in which it is implemented is in pretty well any state; no synchronization with other internal .DLL state can be relied upon. Thus, it is recommended that the implementation of this function indeed do nothing more than set internal global variables.

Argument	Type	Description
fTrace	BOOL	TRUE if debugging is enabled, FALSE otherwise.
lpOrpcInitArgs	LPORPC_INIT_ARGS	Typically NULL; see comments above for MAC COM debuggers or in-process debuggers.
return value	BOOL	TRUE if the function was successful (the .DLL understood and executed the request), FALSE otherwise