TraceRegister

[This is preliminary documentation and subject to change.]

Use the TraceRegister function to register services or applications with the tracing DLL. Its successful return value is an identifier that provides a handle to subsequent tracing functions available in Windows NT Routing and Remote Access Service. This function, or its extended functionality counterpart TraceRegisterEx, must be called before any other tracing functions are called. TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

DWORD TraceRegister(
  IN LPCTSTR lpszCallerName  //caller name
);
 

Parameters

lpszCallerName

Pointer to a null-terminated string containing the service or application name being registered. This is the name with which the service tracing functions will identify the caller.

Return Values

If successful, this function will return a DWORD to be used as the service or application's identifier (handle) for subsequent calls to tracing functions.

If the function fails, INVALID_TRACEID is returned. This indicates the caller could not be registered. Call GetLastError to retrieve the error code.

Remarks

Upon successful execution of TraceRegister, configuration for the service or application calling TraceRegister will be created and kept in the registry path \System\CurrentControlSet\Services\Tracing\<lpszCallerName> under the HKEY_LOCAL_MACHINE key. Such configuration parameters are kept intact, even if the service or application is deregistered from tracing utilities by calling TraceDeregister. If the registry entries cannot be created, the call to TraceRegister will fail. There are certain values within this key that can be modified to change the behavior of trace output.

EnableConsoleTracing

A REG_DWORD that determines whether tracing to the console is enabled. Console tracing is enabled if the value is non-zero. The default value is 1.

EnableFileTracing

A REG_DWORD that determines whether tracing information should be sent to a file called lpzsCallerName.log. File tracing is enabled if the value is non-zero. The default value is 1.

ConsoleTracingMask

A REG_DWORD that regulates whether output from an extended tracing function call is directed to the console. The bits in the high-order word correspond to components in the client; if a call to an extended output function has the flag TRACE_USE_MASK set, the value of ConsoleTracingMask is compared to the flag sent to the function to determine whether to send output to the console. The default value is 0xFFFF0000.

FileTracingMask

A REG_DWORD that works in a similar way to ConsoleTracingMask, regulating whether the extended tracing function calls direct their output to File Tracing. The default value is 0xFFFF0000.

MaxFileSize

A REG_DWORD that defines the maximum size a tracing file can become before it is renamed. The default value is 0x10000.

FileDirectory

A REG_EXPAND_SZ that controls the directory in which the tracing file is created. The default is %windir%\tracing.

QuickInfo

  Windows NT: Use version 5.0 and later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in rtutils.h.
  Import Library: Link with rtutils.lib.

See Also

TraceRegisterEx, TraceDeregister, TracePrintf, TraceVprintf, TracePuts, TraceDump, GetLastError