Geoff Chappell, Software Analyst
A classic event provider calls this function from within a notification callback to learn the “enable level” of the event tracing session that is the subject of the notification. This level is whatever the provider defines it to be. The overall purpose is that different events can be associated with different levels, typically according to severity. A conventional interpretation ranges from 1 for critical to 5 for verbose. The controller of an event tracing session, mostly usefully one that knows the provider’s definitions, may then set a level to indicate that it wants events at this level and below but not the less important events that have a numerically higher level. The event provider that learns of this setting can then not waste time even trying to trace events that the tracing session will ignore.
UCHAR EtwGetTraceEnableLevel (TRACEHANDLE TraceHandle);
The TraceHandle represents the tracing session for the duration of the callback routine. The provider can have got this handle by calling the EtwGetTraceLoggerHandle function from within the WMIDPREQUEST callback routine that it supplied when registering through the EtwRegisterTraceGuids function.
A successful call returns the level, which may be zero. Failure is indicated by returning zero, but having set a non-zero Win32 error code as the thread’s last error (such that it may be retrieved through such functions as GetLastError).
Although zero may not often be useful for the enable level, it is not inconceivable that a tracing session does mean to specify zero (if only temporarily). The caller who wants to distinguish whether zero as the return value is success or failure will need to have cleared the last error in advance.
The EtwGetTraceEnableLevel function is exported by name from NTDLL in version 5.2 and higher. It has higher-level availability as a forward from the ADVAPI32 export GetTraceEnableLevel in its versions 5.2 and higher.
This note is concerned only with the function as implemented in NTDLL version 5.2 and higher. The earlier implementations in ADVAPI32 versions 5.0 and 5.1 are left for separate treatment some other time.
The EtwGetTraceEnableLevel function is not documented. Well-behaved user-mode software would call the documented GetTraceEnableLevel function instead. Note, however, that a strict reading of Microsoft’s documentation prohibits calling the higher-level function, but not the lower-level, from a DllMain routine. For some hint that Microsoft has experience either of or closely related to this point, see the cautionary note about the loader lock in Microsoft’s documentation of the WMIDPREQUEST callback function.
This function exists merely to help the provider crack the enable level from the particular encoding that the TRACEHANDLE should have in the expected circumstances.
As always for a TRACEHANDLE, the low 16 bits are the logger ID. Except that 0xFFFF conventionally represents the NT Kernel Logger, the logger ID is a 0-based index into the kernel’s list of loggers and must be less than MAXLOGGERS (64 in the applicable versions, at least to the original Windows 10), else the function fails, with ERROR_INVALID_HANDLE as its error code.
In the expected circumstances, the TRACEHANDLE is in fact a TRACE_ENABLE_CONTEXT. Its Level member is in effect the third least significant byte of the TRACEHANDLE. If the whole TRACEHANDLE is zero, then this interpretation is implausible and the function fails, again with ERROR_INVALID_HANDLE as its error code.