The EtwRegister function registers the event provider and must be called before a provider can start tracing. The EtwRegister function is the kernel mode counterpart to the user-mode EventRegister function. The function can also provide a pointer to an optional callback function that can be used to provide additional event filtering capabilities.
NTSTATUS EtwRegister( LPCGUID ProviderId, PETWENABLECALLBACK EnableCallback, PVOID CallbackContext, PREGHANDLE RegHandle );
A pointer to the event provider GUID.
A pointer to an optional callback function. The callback function provides additional event filtering capabilities. The callback function is user-defined.
The function passes back the optional callback context when a callback is made. You can specify the optional context when you register a provider. The CallbackContext parameter supports the scenarios in which one callback is shared by multiple providers, as in a C++ class. The CallbackContext provides a way to distinguish the target provider instances for the enable callback.
A pointer to a variable that receives the provider registration handle if the function call is successful.
The EtwRegister function returns a status code from the following list:
||Indicates that event provider was successfully registered with ETW.|
||Indicates that the parameter was not valid.|
||Indicates that the request failed for the reason specified by the NTSTATUS value. See Ntstatus.h for detailed information about the actual status return code.|
Before a kernel-mode driver can trace events, the driver must register as an event provider using the EtwRegister function. When a kernel mode driver calls EtwRegister, the function returns a registration handle. This registration handle can be used to test whether a keyword or level is enabled for a specific provider and to call event tracing and logging functions. After tracing is complete, a driver must call the EtwUnregister function to unregister the provider. For every call to EtwRegister there must be a corresponding call to EtwUnregister. Failure to unregister the event provider can cause errors when the process is unloaded because the callback functions associated with the process are no longer valid. No tracing calls should be made that fall outside of the code bounded by the EtwRegister and EtwUnregister functions. For the best performance, you can call the EtwRegister function in your DriverEntry routine and the EtwUnregister function in your DriverUnload routine.
Callers of EtwRegister must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.
|Minimum supported client||Available in Windows Vista and later versions of Windows.|
|Header||wdm.h (include Wdm.h, Ntddk.h)|
|DDI compliance rules||PowerIrpDDis|