EventRegister function (evntprov.h)

Registers an ETW event provider, creating a handle that can be used to write ETW events.

Syntax

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Parameters

[in] ProviderId

GUID that uniquely identifies the provider, sometimes called a control GUID. This must be a stable identifier so that trace controllers can use the GUID to subscribe to events from this provider.

[in, optional] EnableCallback

Optional EnableCallback that ETW will invoke when a trace session enables or disables this provider. Use NULL if no callback is needed.

[in, optional] CallbackContext

Optional context data that ETW will provide when invoking EnableCallback. Use NULL if no callback context is needed.

[out] RegHandle

Receives the event provider registration handle. The handle is used in subsequent calls to provider APIs such as EventWrite, EventProviderEnabled, and EventRegister.

Before your provider unloads or exits, free the provider registration handle by calling EventUnregister. A DLL that unloads without freeing all of the provider handles that it registered may cause the process to crash.

Return value

Returns ERROR_SUCCESS if successful.

The error code returned by EventRegister is primarily intended for use in debugging and diagnostic scenarios. Most production code should continue to run even if an ETW provider failed to register, so release builds should usually ignore the error code returned by EventRegister.

Remarks

EventRegister creates a handle that you can use to write ETW events via EventWrite, EventWriteTransfer, or EventWriteEx.

Note

Most event providers will not call EventRegister directly. Instead, most event providers are implemented using an ETW framework that wraps the calls to EventRegister, EventWrite, and EventUnregister. For example, you might write an event manifest and then use the Message Compiler to generate C/C++ code for the events, or you might use TraceLogging to avoid the need for a manifest.

Registration of an event provider should not be confused with installation of an event provider's manifest.

  • The EventRegister API performs registration of an event provider to create a provider handle. This is a process-scope operation (the handle is valid only within the process). The handle can be used to write ETW events. All events written using the handle will be tagged with the ProviderId that was specified during provider registration. It is not necessary to install a manifest to write events or capture traces (though installing the manifest may be necessary for decoding the provider's events or for the provider to work with Event Log).
  • The wevtutil.exe tool is used to install or uninstall an event provider's manifest. Installation of an event provider manifest means that information from the manifest is recorded on the system. The recorded information is system-global and persists until the manifest is uninstalled. The recorded information includes the names, GUIDs, channels, and resource DLL paths of the providers defined in the manifest. The information from the manifest is used by trace decoding tools and Event Log.

Most components will register their event provider at component initialization and will unregister their event provider at component shutdown. For example, an application (EXE) might register during application startup and unregister during application exit. A dynamic library (DLL) might register in DllMain during process attach and might unregister in DllMain during process detach.

Since event tracing is a debugging/diagnostic concern and is not normally application-critical functionality, most retail applications should silently ignore failures returned by EventRegister. In case of failure, EventRegister will set the RegHandle parameter to zero so that subsequent uses of the RegHandle (i.e. in calls to EventWrite and EventUnregister) will have no effect.

Each process can register up to 1,024 providers. However, you should limit the number of providers that your component registers to one or two. This limit includes providers registered using this function and providers registered using RegisterTraceGuids.

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

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header evntprov.h
Library Advapi32.lib
DLL Advapi32.dll

See also

EnableCallback

EventWrite

EventUnregister