Geoff Chappell, Software Analyst
A classic event provider calls this function from within a notification callback to learn the “enable flags” of the event tracing session that is the subject of the notification. These flags are whatever the provider defines them to be. The overall purpose is that different events can be associated with different selections of bits in the flags. The controller of an event tracing session, mostly usefully one that knows the provider’s definitions, may then set some combination of the flags to indicate that it wants the matching events but no others. The event provider that learns of this setting can then not waste time even trying to trace events that the tracing session will ignore.
ULONG EtwGetTraceEnableFlags (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 flags, 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 flags, it is not inconceivable that a tracing session does mean them to be 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 EtwGetTraceEnableFlags 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 GetTraceEnableFlags 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 EtwGetTraceEnableFlags function is not documented. Well-behaved user-mode software would call the documented GetTraceEnableFlags 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 flags 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 EnableFlags member is in effect the high 32 bits 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.