WMIDPREQUEST callback function (evntrace.h)

A RegisterTraceGuids-based ("Classic") event provider implements this function to receive enable or disable notification requests from controllers.

The WMIDPREQUEST type defines a pointer to this callback function. ControlCallback is a placeholder for the application-defined function name.

Syntax

WMIDPREQUEST Wmidprequest;

ULONG Wmidprequest(
  [in] WMIDPREQUESTCODE RequestCode,
       PVOID RequestContext,
       ULONG *BufferSize,
  [in] PVOID Buffer
)
{...}

Parameters

[in] RequestCode

Request code. This will be one of the following values.

Value Meaning
WMI_ENABLE_EVENTS Enables the provider or changes provider configuration.
WMI_DISABLE_EVENTS Disables the provider.

RequestContext

Provider-defined context. The provider uses the RequestContext parameter of
RegisterTraceGuids to specify the context.

BufferSize

Reserved for internal use.

[in] Buffer

Pointer to a WNODE_HEADER structure that contains information about the event tracing session for which the provider is being enabled or disabled.

Return value

You should return ERROR_SUCCESS if the callback succeeds. Note that ETW ignores the return value for this function except when a controller calls EnableTrace to enable a provider and the provider has not yet called RegisterTraceGuids. When this occurs, RegisterTraceGuids will return the return value of this callback if the registration was successful.

Remarks

This function is specified using the RegisterTraceGuids function. When the controller calls the EnableTrace function to enable, disable, or change the enable flags or level, ETW calls this callback. The provider enables or disables itself based on the RequestCode value. Typically, the provider uses this value to set a global flag to indicate its enabled state.

The provider defines its interpretation of being enabled or disabled. Generally, if a provider is enabled, it generates events, but while it is disabled, it does not.

ETW does not pass the enable flags and enable level that the controller passes to the EnableTrace function to this callback. To retrieve this information, call the GetTraceEnableFlags and GetTraceEnableLevel functions, respectively.

You also need to retrieve the session handle in this callback for future calls. To retrieve the session handle, call the GetTraceLoggerHandle function.

Your callback function must not call anything that may incur LoadLibrary (more specifically, anything that requires a loader lock).

Examples

For an example implementation of a ControlCallback function, see Writing Classic Events.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header evntrace.h

See also

EnableTrace

GetTraceEnableFlags

GetTraceEnableLevel

GetTraceLoggerHandle

RegisterTraceGuids

WNODE_HEADER