TraceLoggingRegister function (traceloggingprovider.h)
Registers a TraceLogging provider so that it can be used to log events. The registration is valid until the provider is unregistered or the process exits.
Syntax
TLG_STATUS TraceLoggingRegister(
TraceLoggingHProvider hProvider
);
Parameters
hProvider
The handle of the TraceLogging provider to register. The handle must not already be registered.
Return value
If you call this function from user-mode code, the function returns an
HRESULT. Use the SUCCEEDED() macro to determine whether the function
succeeds.
If you call this function from kernel-mode code, the function returns an
NTSTATUS. Use the NT_SUCCESS() macro to determine whether the function
succeeds.
Note
The error code returned by TraceLoggingRegister 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 TraceLoggingRegister.
Remarks
When a component starts running, any TraceLogging provider handle in the
component will be in an unregistered state and any attempts to use the
provider's handle to generate events will be silently ignored. Before the
provider can write any events, you need to register the provider using
TraceLoggingRegister. You will typically do this during component startup,
e.g. in main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH), or
DriverEntry. At component shutdown, unregister the provider by calling
TraceLoggingUnregister.
Do not call TraceLoggingRegister on a provider handle that is already registered. You can unregister a handle and then register it again if necessary, though repeatedly registering and unregistering the handle can cause performance issues and should be avoided (i.e. do not register, write a few events, and then unregister; instead, register once at component startup and unregister at component shutdown).
TraceLoggingRegister is not thread-safe with regards to other calls to TraceLoggingRegister or TraceLoggingUnregister on the same handle. Do not call TraceLoggingRegister if it is possible that another thread might call TraceLoggingRegister or TraceLoggingUnregister on the same handle at the same time.
If TraceLoggingRegister fails, the provider handle will remain unregistered and all uses of the provider handle will be safe no-ops. In particular, it is a safe no-op to call TraceLoggingWrite or TraceLoggingUnregister with an unregistered provider handle.
Important
If your DLL or driver calls TraceLoggingRegister on a provider handle, it must call TraceLoggingUnregister on that provider handle before the DLL or driver unloads. If a DLL unloads without calling TraceLoggingUnregister, the process may subsequently crash. If a driver unloads without calling TraceLoggingUnregister, the system may subsequently crash. The TraceLoggingRegister function establishes an ETW configuration callback, and TraceLoggingUnregister cancels the callback. If the callback is not cancelled and the module unloads, a crash will occur the next time ETW tries to invoke the callback.
Warning
If your driver calls TraceLoggingRegister and then encounters an error during DriverEntry, it must call TraceLoggingUnregister before returning the error from DriverEntry. Normal driver cleanup routines will not be called if the driver returns an error from DriverEntry, and failure to call TraceLoggingUnregister will cause the system to crash.
TraceLoggingRegister does the following:
- Calls EventRegister to open the connection to ETW.
- If EventRegister succeeds, calls TraceLoggingSetInformation with InformationClass EventProviderSetTraits to configure the provider for TraceLogging support.
A call to TraceLoggingRegister is the same as a call to TraceLoggingRegisterEx with NULL for the callback and context parameters. Use TraceLoggingRegisterEx if you need to receive an ETW Enable Callback when sessions enable or disable your provider.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Header | traceloggingprovider.h |
| Library | Advapi32.lib |