EtwActivityIdControlKernel function

Article
10/26/2017

The EtwActivityIdControlKernel function creates and sets the current activity identifier and can be used on user-mode and kernel-mode threads.

Syntax

NTSTATUS EtwActivityIdControlKernel(
  _In_    ULONG   ControlCode,
  _Inout_ LPCGUID *ActivityId
);

Parameters

ControlCode [in]
Specifies the action to take with the current thread's ActivityId. The ControlCode parameter can be one of the following defined values.

Value	Meaning
EVENT_ACTIVITY_CTRL_GET_ID	Returns the current thread's activity identifier in the ActivityId parameter.
EVENT_ACTIVITY_CTRL_SET_ID	Sets the current thread's activity identifier to the value specified in ActivityId. Note that the ActivityId you pass to this function does not necessarily have to be one created by EVENT_ACTIVITY_CTRL_CREATE_ID or EVENT_ACTIVITY_CTRL_CREATE_SET_ID control code. You can use any value that fits inside a GUID, including any available local value that would serve your need for some type of activity identifier.

EVENT_ACTIVITY_CTRL_GET_ID

Returns the current thread's activity identifier in the ActivityId parameter.

EVENT_ACTIVITY_CTRL_SET_ID

Sets the current thread's activity identifier to the value specified in ActivityId. Note that the ActivityId you pass to this function does not necessarily have to be one created by EVENT_ACTIVITY_CTRL_CREATE_ID or EVENT_ACTIVITY_CTRL_CREATE_SET_ID control code. You can use any value that fits inside a GUID, including any available local value that would serve your need for some type of activity identifier.

ActivityId [in, out]
A pointer to the GUID that uniquely identifies the activity. This parameter is an input parameter when the ControlCode is EVENT_ACTIVITY_CTRL_SET_ID and an output parameter when the ControlCode is EVENT_ACTIVITY_CTRL_GET_ID. The ActivityId parameter provides a way to group related events and is used in end-to-end tracing.

Return value

Returns ERROR_SUCCESS if successful or the following value on error.

Return code	Description
ERROR_INVALID_PARAMETER	One or more of the parameters is not valid.

Remarks

The EtwActivityIdControlKernel function operates on the ActivityId of the current thread. This differs from EtwActivityIdControl in that the EtwActivityIdControlKernel function uses the kernel's thread storage and not the thread environment block (TEB). Consequently, EtwActivityIdControlKernel can be used on any thread. EtwActivityIdControlKernel supports a subset of the ControlCode values available to the EtwActivityIdControl routine.

Requirements

Minimum supported client	Windows 8.1
Minimum supported server	Windows Server 2012 R2
Target platform	Desktop
Header	Wdm.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe

Share via