RegisterTraceGuids function

The RegisterTraceGuids function registers an event trace provider and the event trace classes that it uses to generate events. This function also specifies the function the provider uses to enable and disable tracing.

Syntax

ULONG RegisterTraceGuids(
  _In_    WMIDPREQUEST             RequestAddress,
  _In_    PVOID                    RequestContext,
  _In_    LPCGUID                  ControlGuid,
  _In_    ULONG                    GuidCount,
  _Inout_ PTRACE_GUID_REGISTRATION TraceGuidReg,
  _In_    LPCTSTR                  MofImagePath,
  _In_    LPCTSTR                  MofResourceName,
  _Out_   PTRACEHANDLE             RegistrationHandle
);

Parameters

RequestAddress [in]

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

RequestContext [in]

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

ControlGuid [in]

GUID of the registering provider.

GuidCount [in]

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

TraceGuidReg [in, out]

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.

MofImagePath [in]

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.

MofResourceName [in]

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.

RegistrationHandle [out]

Pointer to the provider's registration handle. Use this handle when you call the UnregisterTraceGuids function.

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 table includes some common errors and their causes.

Remarks

Providers call this function.

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.

Requirements

See also

EnableTrace

UnregisterTraceGuids