CDebugReportHook Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Use this class to send debug reports to a named pipe.

class CDebugReportHook

Public Constructors

NameDescription
CDebugReportHook::CDebugReportHookCalls SetPipeName, SetTimeout, and SetHook.
CDebugReportHook::~CDebugReportHookCalls CDebugReportHook::RemoveHook.

Public Methods

NameDescription
CDebugReportHook::CDebugReportHookProc(Static) The custom reporting function that is hooked into the C run-time debug reporting process.
CDebugReportHook::RemoveHookCall this method to stop sending debug reports to the named pipe and restore the previous report hook.
CDebugReportHook::SetHookCall this method to start sending debug reports to the named pipe.
CDebugReportHook::SetPipeNameCall this method to set the machine and name of the pipe to which the debug reports will be sent.
CDebugReportHook::SetTimeoutCall this method to set the time in milliseconds that this class will wait for the named pipe to become available.

Create an instance of this class in debug builds of your services or applications to send debug reports to a named pipe. Debug reports are generated by calling _CrtDbgReport or using a wrapper for this function such as the ATLTRACE and ATLASSERT macros.

Use of this class allows you to interactively debug components running in non-interactive window stations.

Note that debug reports are sent using the underlying security context of the thread. Impersonation is temporarily disabled so that debug reports can be viewed in situations where impersonation of low privilege users is taking place, such as in web applications.

Header: atlutil.h

Calls SetPipeName, SetTimeout, and SetHook.

CDebugReportHook(
    LPCSTR szMachineName = ".",
    LPCSTR szPipeName = "AtlsDbgPipe",
    DWORD dwTimeout = 20000) throw();

Parameters

szMachineName
The name of the machine to which the debug output should be sent. Defaults to the local machine.

szPipeName
The name of the named pipe to which the debug output should be sent.

dwTimeout
The time in milliseconds that this class will wait for the named pipe to become available.

Calls CDebugReportHook::RemoveHook.

~CDebugReportHook() throw();

The custom reporting function that is hooked into the C run-time debug reporting process.

static int __cdecl CDebugReportHookProc(
    int reportType,
    char* message,
    int* returnValue) throw();

Parameters

reportType
The type of the report (_CRT_WARN, _CRT_ERROR, or _CRT_ASSERT).

message
The message string.

returnValue
The value that should be returned by _CrtDbgReport.

Return Value

Returns FALSE if the hook handles the message in question completely so that no further reporting is required. Returns TRUE if _CrtDbgReport should report the message in the normal way.

Remarks

The reporting function attempts to open the named pipe and communicate with the process at the other end. If the pipe is busy, the reporting function will wait until the pipe is free or the timeout expires. The timeout can be set by the constructor or a call to CDebugReportHook::SetTimeout.

The code in this function is executed in the underlying security context of the calling thread, that is, impersonation is disabled for the duration of this function.

Call this method to stop sending debug reports to the named pipe and restore the previous report hook.

void RemoveHook() throw();

Remarks

Calls _CrtSetReportHook2 to restore the previous report hook.

Call this method to start sending debug reports to the named pipe.

void SetHook() throw();

Remarks

Calls _CrtSetReportHook2 to have debug reports routed through CDebugReportHookProc to the named pipe. This class keeps track of the previous report hook so that it can be restored when RemoveHook is called.

Call this method to set the machine and name of the pipe to which the debug reports will be sent.

BOOL SetPipeName(
    LPCSTR szMachineName = ".",
    LPCSTR szPipeName = "AtlsDbgPipe") throw();

Parameters

szMachineName
The name of the machine to which the debug output should be sent.

szPipeName
The name of the named pipe to which the debug output should be sent.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the time in milliseconds that this class will wait for the named pipe to become available.

void SetTimeout(DWORD dwTimeout);

Parameters

dwTimeout
The time in milliseconds that this class will wait for the named pipe to become available.

Classes

Show: