Edit

Share via

RegisterTraceGuidsA function (evntrace.h)

  • Article

The RegisterTraceGuids function registers a Classic (Windows 2000-style) ETW event trace provider and the event trace classes that it uses to generate events. This function also specifies the callback function the system uses to enable and disable tracing from the provider.

This function is obsolete. New code should use EventRegister to register a Windows Vista-style (Crimson) ETW event trace provider.

Syntax

ULONG WMIAPI RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     TRACEGUID_HANDLE         *RegistrationHandle
);

Parameters

[in] RequestAddress

Pointer to a ControlCallback function that receives notification when the provider is enabled or disabled by an event tracing session. The EnableTrace function triggers this callback.

[in] RequestContext

Pointer to an optional provider-defined context that ETW passes to the function specified by RequestAddress.

[in] ControlGuid

Control GUID (Provider ID) of the registering provider.

[in] GuidCount

Number of elements in the TraceGuidReg array. If TraceGuidReg is NULL, set this parameter to 0.

[in, out] TraceGuidReg

Pointer to an array of
TRACE_GUID_REGISTRATION structures.

Each element identifies a category of events that the provider provides.

On input, the Guid member of each structure contains an event trace class GUID assigned by the registering provider. The class GUID identifies a category of events that the provider provides. Providers use the same class GUID to set the Guid member of EVENT_TRACE_HEADER when calling the TraceEvent function to log the event.

On output, the RegHandle member receives a handle to the event's class GUID registration. If the provider calls the TraceEventInstance function, use the RegHandle member of TRACE_GUID_REGISTRATION to set the RegHandle member of EVENT_INSTANCE_HEADER.

This parameter can be NULL if the provider calls only the TraceEvent function to log events. If the provider calls the TraceEventInstance function to log events, this parameter cannot be NULL.

[in] MofImagePath

This parameter is not supported. Set to NULL. You should use Mofcomp.exe to register the MOF resource during the setup of your application. For more information see, Publishing Your Event Schema.

Windows XP with SP1, Windows XP and Windows 2000: Pointer to an optional string that specifies the path of the DLL or executable program that contains the resource specified by MofResourceName. This parameter can be NULL if the event provider and consumer use another mechanism to share information about the event trace classes used by the provider.

[in] MofResourceName

This parameter is not supported. Set to NULL. You should use Mofcomp.exe to register the MOF resource during the setup of your application. For more information see, Publishing Your Event Schema.

Windows XP with SP1, Windows XP and Windows 2000: Pointer to an optional string that specifies the string resource of MofImagePath. The string resource contains the name of the binary MOF file that describes the event trace classes supported by the provider.

[out] RegistrationHandle

Receives the provider's registration handle. Use the returned handle when you call the UnregisterTraceGuids function.

Important

All registration handles created by a DLL or driver must be unregistered before the DLL or driver unloads. If the provider is not unregistered, a crash will occur when ETW tries to invoke the provider's callback.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following are some common errors and their causes.

Important

 This function can also return the value returned by ControlCallback if a controller calls EnableTrace to enable the provider and the provider has not yet called RegisterTraceGuids. When this occurs, RegisterTraceGuids will return the return value of the callback if the registration was successful.

  • ERROR_INVALID_PARAMETER

    One of the following is true:

    • RequestAddress is NULL.
    • ControlGuid is NULL.
    • RegistrationHandle is NULL.

    Windows XP and Windows 2000: TraceGuidReg is NULL or GuidCount is less than or equal to zero.

Remarks

Note

Most developers will not call this function directly. Instead, developers will typically use an ETW framework. For example, TMF-based WPP manages the calls to RegisterTraceGuids, TraceMessage, and UnregisterTraceGuids on your behalf.

This function opens a Classic (Windows 2000-style) event provider handle that can be used to write MOF and TMF-based WPP ETW events via TraceEvent, TraceEventInstance, TraceMessage, and TraceMessageVa.

Note

To open a Windows Vista-style provider handle that writes manifest-based or TraceLogging-based ETW events via EventWrite, use EventRegister.

If the provider's ControlGuid has been previously registered and enabled, subsequent registrations that reference the same ControlGuid are automatically enabled.

A process can register up to 1,024 provider GUIDs; however, you should limit the number of providers that your process registers to one or two. This limit includes those registered using this function and the EventRegister function.

Prior to Windows Vista: There is no limit to the number of providers that a process can register.

Examples

For an example that uses RegisterTraceGuids, see Writing Classic Events.

Note

The evntrace.h header defines RegisterTraceGuids as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header evntrace.h
Library Sechost.lib on Windows 8.1 and Windows Server 2012 R2; Advapi32.lib on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista and Windows XP
DLL Sechost.dll on Windows 8.1 and Windows Server 2012 R2; Advapi32.dll on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista and Windows XP

See also

EnableTrace

UnregisterTraceGuids