DRAFT: Take more than your usual care.

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

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.

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. Whether this succeeds or fails, the function then writes the event. The function’s success or failure is at writing the event.