Geoff Chappell, Software Analyst
DRAFT: Take more than your usual care.
This function writes an event and starts the corresponding scenario.
NTSTATUS EtwWriteStartScenario ( REGHANDLE RegHandle, PCEVENT_DESCRIPTOR EventDescriptor, GUID *ActivityId, ULONG UserDataCount, PEVENT_DATA_DESCRIPTOR UserData);
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.
The function returns STATUS_SUCCESS if successful, else a negative error code.
The EtwWriteStartScenario function is exported by name from the kernel in version 6.0 and higher.
The EtwWriteStartScenario function is not documented. Neither is it declared in any header from any Windows Driver Kit (WDK).
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.