TraceRegisterEx

[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.]

The TraceRegisterEx function registers services or applications with the tracing API. TraceRegisterEx differentiates itself from TraceRegister by providing extended flexibility with regard to the creation or reading of registry keys.

Successful execution of TraceRegisterEx returns an identifier used as a handle to subsequent tracing functions available in Windows NT/Windows 2000. This function, or its counterpart TraceRegister, must be called before any other tracing functions are called. However, TraceRegisterEx should not be called from within DllMain, the DLL entry-point function.

DWORD TraceRegisterEx(
  LPCTSTR lpszCallerName,
  DWORD dwFlags
);

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 will identify the caller.
• dwFlags
  [in] Specifies the flags that control the nature of the calling service or application's registration. Ensure dwFlags is one or more of the following:

  Value	Meaning
  TRACE_USE_CONSOLE	Tracing output is sent to the console; using this parameter avoids loading or writing settings from the registry.
  TRACE_USE_FILE	Tracing output is sent to a file; using this parameter avoids reading or writing settings from the registry.

Return Value

Success returns a DWORD to be used as the service or application identifier (handle) for subsequent calls to tracing functions.

Value	Meaning
INVALID_TRACEID	The caller was not registered. Call GetLastError to retrieve the error code.

Remarks

If no flags are passed to TraceRegisterEx (if dwFlags is zero), TraceRegisterEx behaves exactly as TraceRegister.

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

Upon successful execution of TraceRegisterEx, configuration for the service or application calling TraceRegisterEx is taken from the parameters passed as dwFlags, and registry reads or writes do not occur. If the value of dwFlags is zero, then a call to TraceRegisterEx behaves exactly as a call to TraceRegister, and initialization and configuration parameters are created and kept in the registry path:

HKEY_LOCAL_MACHINE
     Software
          Microsoft
               Tracing
                    client name

Requirements

Server	Requires Windows Server 2003 or Windows 2000 Server.
Redistributable	Requires RRAS download on Windows NT Server 4.0 SP3 and later.
Header	Declared in Rtutils.h.
Library	Use Rtutils.lib.
DLL	Requires Rtutils.dll.
Unicode	Implemented as TraceRegisterExW (Unicode) and TraceRegisterExA (ANSI).

See Also

About Tracing
Tracing Reference
TraceRegister
TracePrintfEx
TraceVprintfEx
TracePutsEx
TraceDumpEx