TraceRegister

[This Tracing API is available for use in the operating systems listed in the Requirements section. It may be altered or unavailable in subsequent versions. Instead use the Event Tracing API.]

Use the TraceRegister function to register services or applications with the tracing API. Its successful return value is an identifier that provides a handle to subsequent tracing functions available in Windows NT/Windows 2000. This function, or its extended functionality counterpart TraceRegisterEx, must be called before any other tracing functions are called. However, TraceRegister should not be called from within DllMain, the DLL entry-point function.

DWORD TraceRegister(
  LPCTSTR lpszCallerName
);

Parameters

• lpszCallerName
  [in] Pointer to a null-terminated string that contains the service or application name being registered. This is the name with which the service tracing functions identifies the caller.

Return Value

If successful, this function returns 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

TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

Upon successful execution of TraceRegister, a configuration for the service or application calling TraceRegister is created and kept in the registry path:

HKEY_LOCAL_MACHINESoftware
     Microsoft
          Tracing
               client name

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 fails. There are certain values within this key that are 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 is 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, regulates 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 becomes 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.

Requirements

See Also

About Tracing
Tracing Reference
TraceRegisterEx
TraceDeregister
TracePrintf
TraceVprintf
TracePuts
TraceDump