EtwWriteStartScenario

This function writes an event and starts the corresponding scenario.

Declaration

NTSTATUS 
EtwWriteStartScenario (
    REGHANDLE RegHandle, 
    PCEVENT_DESCRIPTOR EventDescriptor, 
    GUID *ActivityId, 
    ULONG UserDataCount, 
    PEVENT_DATA_DESCRIPTOR UserData);

Arguments

The RegHandle argument specifies an event provider.

The EventDescriptor argument is the address of a structure that describes an event to write.

The ActivityId argument is the address of a GUID to associate with this instance of the event and with the scenario. If the GUID that it points to is all zeroes, the function replaces it.

The UserDataCount argument specifies the number of data elements to write with the event. The UserData argument is the address of an array of structures that each describe one of those data elements.

Return Value

The function returns STATUS_SUCCESS if successful, else a negative error code.

Availability

The EtwWriteStartScenario function is exported by name from the kernel in version 6.0 and higher.

Documentation Status

The EtwWriteStartScenario function is not documented. Neither is it declared in any header from any Windows Driver Kit (WDK).

Pending discovery of Microsoft’s names and types for the function’s arguments, this note treats the function as the documented EtwWrite function with extra behaviour and supposes that names and types are duplicated.

Behaviour

The EventDescriptor and ActivityId arguments are required. If either is NULL, the function returns STATUS_INVALID_PARAMETER.

The RegHandle argument is a handle in the sense of representing a registration of an event provider. In version 6.2 and higher, it (or its low 32-bits on 32-bit Windows) is a pointer to an ETW_REG_ENTRY. If instead it is NULL or if the given event is not enabled for the given provider, the function returns STATUS_INVALID_HANDLE.

The activity identifier will be written with the event but also will become associated with the started scenario. Ideally, it is unique. If it is given as all zeroes, the function replaces it with a newly created activity identifier. Failure at this, meaning the EtwActivityIdCreate case of ZwTraceControl, is failure for the function. (That the function does not cut through to the internal routine that creates activity identifiers supports the present classification of this function within the Windows Diagnostic Infrastructure, built on top of Event Tracing for Windows, not within it, no matter that the function has the Etw prefix.)

With this validation and preparation done, the function proceeds to its two essential tasks. First, it writes the event. Success or failure at this becomes success or failure for the function, but not without at least attempting to start the scenario. To be clear, the function tries to start the scenario even if this event that starts it is not written, and the function’s success means the event was written and says nothing of whether a scenario started.

The scenario to start is the first (ideally, the one) for which the given event is configured as the start event. All being well, the function would create an enabled instance of the scenario and associate it with the given activity ID. If any enabled instance already has this activity ID, then the function has nothing to start. There can anyway be no more than 128 instances in-flight at any given time.