EtwWriteEndScenario

This function writes an event, but first ends a scenario.

Declaration

NTSTATUS 
EtwWriteEndScenario (
    REGHANDLE RegHandle, 
    PCEVENT_DESCRIPTOR EventDescriptor, 
    LPCGUID 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 which is already associated with the scenario, i.e., from having been given to or generated by the matching EtwWriteStartScenario.

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 EtwWriteEndScenario function is exported by name from the kernel in version 6.0 and higher.

Documentation Status

The EtwWriteEndScenario 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.

With this validation and preparation done, the function proceeds to its two essential tasks. First, it ends the scenario, if any, that’s represented by the ActivityId. Second, even if unable to end the scenario, the function then writes the event. The function’s success or failure is at writing the event.