DRAFT: Take more than your usual care.

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).

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: 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 ID 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 ID. Failure at this (meaning the EtwActivityIdCreate case of ZwTraceControl) is failure for the function.

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.