CDebugReportHook Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CDebugReportHook Class.

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

Syntax

class CDebugReportHook

Members

Public Constructors

Public Methods

Remarks

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.

Requirements

Header: atlutil.h

CDebugReportHook::CDebugReportHook

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.

CDebugReportHook::~CDebugReportHook

Calls CDebugReportHook::RemoveHook.

~CDebugReportHook() throw();

CDebugReportHook::CDebugReportHookProc

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.

CDebugReportHook::RemoveHook

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.

CDebugReportHook::SetHook

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.

CDebugReportHook::SetPipeName

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.

CDebugReportHook::SetTimeout

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.

See Also

Classes