Функция RegisterTraceGuidsA (evntrace.h)
Функция RegisterTraceGuids регистрирует поставщик трассировки событий трассировки событий ETW классической (Windows 2000) и классы трассировки событий, которые он использует для создания событий. Эта функция также указывает функцию обратного вызова, которую система использует для включения и отключения трассировки от поставщика.
Эта функция устарела. Новый код должен использовать EventRegister для регистрации поставщика трассировки событий в стиле Windows Vista (Crimson).
Синтаксис
ULONG WMIAPI RegisterTraceGuidsA(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCSTR MofImagePath,
[in] LPCSTR MofResourceName,
[out] TRACEGUID_HANDLE *RegistrationHandle
);
Параметры
[in] RequestAddress
Указатель на функцию ControlCallback, которая получает уведомление, когда поставщик включен или отключен сеансом трассировки событий. Функция EnableTrace активирует этот обратный вызов.
[in] RequestContext
Указатель на необязательный контекст, определенный поставщиком, который ETW передает функции, указанной RequestAddress.
[in] ControlGuid
Управление GUID (идентификатор поставщика) регистратора.
[in] GuidCount
Количество элементов в массиве TraceGuidReg. Если TraceGuidRegNULL, задайте для этого параметра значение 0.
[in, out] TraceGuidReg
Указатель на массив
TRACE_GUID_REGISTRATION структуры.
Каждый элемент определяет категорию событий, которые предоставляет поставщик.
Во входных данных guid член каждой структуры содержит GUID класса трассировки событий, назначенный поставщиком регистрации. GUID класса определяет категорию событий, которые предоставляет поставщик. Поставщики используют тот же GUID класса, чтобы задать член Guid
В выходных данных член RegHandle получает дескриптор регистрации GUID класса события. Если поставщик вызывает функцию TraceEventInstance
Этот параметр может быть значение NULL, если поставщик вызывает только функцию traceEvent traceEvent для регистрации событий. Если поставщик вызывает функцию traceEventInstance
[in] MofImagePath
Этот параметр не поддерживается. Установите значение NULL. Во время настройки приложения следует использовать Mofcomp.exe для регистрации ресурса MOF. Дополнительные сведения см. в публикации схемы событий.
Windows XP с пакетом обновления 1 (SP1), Windows XP и Windows 2000: указатель на необязательную строку, указывающую путь к библиотеке DLL или исполняемой программе, содержащей ресурс, указанный MofResourceName. Этот параметр может быть null, если поставщик событий и потребитель используют другой механизм для совместного использования сведений о классах трассировки событий, используемых поставщиком.
[in] MofResourceName
Этот параметр не поддерживается. Установите значение NULL. Во время настройки приложения следует использовать Mofcomp.exe для регистрации ресурса MOF. Дополнительные сведения см. в публикации схемы событий.
Windows XP с пакетом обновления 1 (SP1), Windows XP и Windows 2000: указатель на необязательную строку, указывающую строковый ресурс MofImagePath. Строковый ресурс содержит имя двоичного MOF-файла, описывающего классы трассировки событий, поддерживаемые поставщиком.
[out] RegistrationHandle
Получает дескриптор регистрации поставщика. Используйте возвращенный дескриптор при вызове функции UnregisterTraceGuids.
Важный
Все дескриптора регистрации, созданные библиотекой DLL или драйвером, необходимо отменить регистрацию перед выгрузкой библиотеки DLL или драйвера. Если поставщик не зарегистрирован, при попытке etW вызвать обратный вызов поставщика произойдет сбой.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемое значение является одним из системных кодов ошибок. Ниже приведены некоторые распространенные ошибки и их причины.
Важный
Эта функция также может возвращать значение, возвращаемое ControlCallback, если контроллер вызывает EnableTrace, чтобы включить поставщик и поставщик еще не вызвал RegisterTraceGuids. При этом RegisterTraceGuids вернет возвращаемое значение обратного вызова, если регистрация прошла успешно.
ERROR_INVALID_PARAMETER
Одно из следующих значений:
- RequestAddressNULL.
- ControlGuidNULL.
- RegistrationHandleNULL.
Windows XP и Windows 2000:TraceGuidReg имеет значение NULL или GuidCount меньше или равно нулю.
Замечания
Заметка
Большинство разработчиков не будут вызывать эту функцию напрямую. Вместо этого разработчики обычно используют платформу ETW. Например, WPP на основе TMF управляет вызовами RegisterTraceGuids, TraceMessageи UnregisterTraceGuids от вашего имени.
Эта функция открывает дескриптор классических (Windows 2000), который можно использовать для записи событий WPF и TMF на основе WPP ETW через TraceEvent, TraceEventInstance, TraceMessageи TraceMessageVa.
Заметка
Чтобы открыть поставщик в стиле Windows Vista, который записывает события на основе манифеста или TraceLogging etW с помощью EventWrite, используйте EventRegister.
Если controlGuid поставщика ранее зарегистрированы и включены, последующие регистрации, ссылающиеся на те же ControlGuid, автоматически включены.
Процесс может зарегистрировать до 1024 идентификаторов GUID поставщика; однако следует ограничить количество поставщиков, регистрирующих процесс, до одного или двух. Это ограничение включает зарегистрированные с помощью этой функции и функцию EventRegister.
до Windows Vista: количество поставщиков, которые может зарегистрировать процесс, не ограничено.
Примеры
Пример использования RegisterTraceGuidsсм. в записи классических событий.
Заметка
Заголовок evntrace.h определяет RegisterTraceGuids в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, который не является кодировкой нейтральным, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows 2000 Server [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | evntrace.h |
| библиотеки |
Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP |
| DLL | Sechost.dll в Windows 8.1 и Windows Server 2012 R2; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP |