TraceRegisterEx

[This is preliminary documentation and subject to change.]

The TraceRegisterEx function registers services or applications with the tracing DLL. TraceRegisterEx differentiates itself from TraceRegister by providing extended flexibility (Ex) 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 Microsoft® Windows NT® Routing and Remote Access Service. This function, or its counterpart TraceRegister, must be called before any other tracing functions are called. If no flags are passed to TraceRegisterEx (if dwFlags is zero), TraceRegisterEx behaves exactly as TraceRegister. TraceDeregister or TraceDeregisterEx should be called when trace functions are no longer needed, in order to free resources.

DWORD TraceRegisterEx(
  IN LPCTSTR lpszCallerName,
  IN DWORD dwFlags OPTIONAL
);
 

Parameters

lpszCallerName

A 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.

dwFlags

Flags that control the nature of the calling service or application's registration. Ensure dwFlags is one or more of the following:

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 Values

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

INVALID_TRACEID

The caller could not be registered. Call GetLastError to retrieve the error code.

Remarks

Upon successful execution of TraceRegisterEx, configuration for the service or application calling TraceRegisterEx will be taken from the parameters passed as dwFlags, and registry reads or writes will not occur. If the value of dwFlags is zero, then a call to TraceRegisterEx will behave exactly as a call to TraceRegister, and initialization and configuration parameters will be created and kept in the registry path \System\CurrentControlSet\Services\Tracing\<lpszCallerName> under the HKEY_LOCAL_MACHINE key.

Make multiple calls to TraceRegisterEx to modify the output settings. This is achieved by changing the parameters passed in dwFlags. When making additional TraceRegisterEx calls to modify dwFlags settings, ensure dwFlags is always non-zero.

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

TraceRegister, TraceDeregisterEx, TracePrintfEx, TraceVprintfEx, TracePutsEx, TraceDumpEx, GetLastError