Функция EventActivityIdControl (evntprov.h)
Создает, запрашивает и задает идентификаторы действий для использования в событиях трассировки событий 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 |