Функция EventActivityIdControl (evntprov.h)

Статья
08/23/2023

Создает, запрашивает и задает идентификаторы действий для использования в событиях трассировки событий Windows.

Синтаксис

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Параметры

[in] ControlCode

Код элемента управления, указывающий операцию, которую необходимо выполнить.

EVENT_ACTIVITY_CTRL_GET_ID

Задает параметру ActivityId значение идентификатора действия текущего потока.
EVENT_ACTIVITY_CTRL_SET_ID

Задает для идентификатора действия текущего потока значение параметра ActivityId .
EVENT_ACTIVITY_CTRL_CREATE_ID

Задает параметру ActivityId значение только что созданного локально уникального идентификатора действия.
EVENT_ACTIVITY_CTRL_GET_SET_ID

Переключает значения параметра ActivityId и идентификатора действия текущего потока. (Сохраняет значение идентификатора действия текущего потока, затем задает для идентификатора действия текущего потока значение параметра ActivityId , а затем задает для параметра ActivityId сохраненное значение.)
EVENT_ACTIVITY_CTRL_CREATE_SET_ID

Задает для параметра ActivityId значение идентификатора действия текущего потока, а затем задает идентификатор действия текущего потока в значение только что созданного локально уникального идентификатора действия.

[in, out] ActivityId

Указатель на буфер, содержащий 128-разрядный идентификатор действия. В зависимости от значения параметра ControlCode этот буфер может быть считывается из и (или) записывается в .

Возвращаемое значение

В случае успешного выполнения возвращает ERROR_SUCCESS.

События трассировки событий Windows, написанные с помощью одного из API EventWrite , будут содержать 128-разрядное поле "идентификатор действия" и при необходимости может содержать 128-разрядное поле "связанный идентификатор действия". Средства обработки трассировки могут использовать значения этих полей для организации событий в группы, называемые действиями.

Предполагается, что все события с нулевым идентификатором действия (т. е. GUID_NULL) не являются частью какого-либо действия.
Предполагается, что все события с определенным ненулевым идентификатором действия являются частью одного действия.
Чтобы указать начало действия, поставщик должен задать opcode значение WINEVENT_OPCODE_START для первого события с определенным ненулевым идентификатором действия (событие start ). Если действие логически вложено в другое действие, поставщик должен задать в поле идентификатора действия, связанного с событием запуска , идентификатор родительского действия.
Чтобы указать конец действия, поставщик должен задать для opcode значение WINEVENT_OPCODE_STOP для последнего события с определенным ненулевым идентификатором действия (событие остановки ).

Чтобы идентификаторы действий были полезны, новые идентификаторы действий должны быть локально уникальными, т. е. один и тот же идентификатор не должен создаваться дважды в трассировки.

Идентификаторы действий можно создавать с помощью EventActivityIdControl, который создает локальные уникальные идентификаторы, которые гарантированно будут уникальными во всех процессах в локальной системе до перезагрузки системы. Вы также можете использовать GUID (глобальный уникальный идентификатор) в качестве идентификатора действия. Guid можно создать с помощью API, например UuidCreate.

Потоки пользовательского режима имеют локальное 128-разрядное значение идентификатора действия потока (идентификатор действия потока). При создании потока идентификатор действия потока инициализируется значением 0 (т. е. GUID_NULL). Идентификатор действия потока можно считывать или обновлять с помощью EventActivityIdControl. Идентификатор действия потока будет использоваться в качестве идентификатора действия для всех событий, написанных EventWrite , и для всех событий, написанных EventWriteTransfer или EventWriteEx , где параметр ActivityId имеет значение NULL.

Важно!

Функция, которая изменяет идентификатор действия потока, должна быть осторожной, чтобы восстановить исходный идентификатор действия перед выходом. В противном случае изменения функции в идентификаторе действия потока будут мешать действиям компонентов, вызывающих функцию.

Использование явно указанного идентификатора действия

В случаях, когда действия не ограничиваются одним потоком или вы хотите избежать возможности вмешательства от других компонентов, перезаписыв идентификатор действия потока, может потребоваться явно указать действия события с помощью поля ActivityIdEventWriteTransfer или EventWriteEx вместо использования идентификатора автоматического действия потока.

Если для записи событий используются манифесты и компилятор сообщений , макросы, созданные с помощью MC.exe -um идентификатора действия потока, в то время как макросы, созданные с помощью MC.exe -km , поддерживают параметр идентификатора действия. Изначально -um макросы работали только в пользовательском режиме, а -km макросы — только в режиме ядра, поэтому код пользовательского режима мог использовать только идентификатор действия текущего потока. Однако начиная с MC.exe версии 10.0.17741 макросы, созданные , MC.exe -km можно использовать как в пользовательском режиме, так и в режиме ядра, поэтому можно использовать для MC.exe -km создания макросов, которые принимают параметр идентификатора действия. (Код, созданный MC, не поддерживает настройку идентификатора связанного действия события.)

При использовании TraceLoggingProvider.h для записи событий макрос TraceLoggingWrite использует идентификатор действия потока, а TraceLoggingWriteActivity принимает параметры для идентификатора действия и связанного идентификатора действия. Кроме того, вы можете использовать классы C++ в TraceLoggingActivity.h для действий TraceLogging.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntprov.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

См. также раздел

EventWriteTransfer