Функция RegisterTraceGuidsA (evntrace.h)
Функция RegisterTraceGuids регистрирует поставщик трассировки событий Windows (в стиле 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] PTRACEHANDLE RegistrationHandle
);
Параметры
[in] RequestAddress
Указатель на функцию ControlCallback , которая получает уведомление, когда поставщик включен или отключен сеансом трассировки событий. Функция EnableTrace активирует этот обратный вызов.
[in] RequestContext
Указатель на необязательный контекст, определяемый поставщиком, который трассировка событий Windows передает функции, указанной параметром RequestAddress.
[in] ControlGuid
Guid элемента управления (идентификатор поставщика) регистрирующегося поставщика.
[in] GuidCount
Количество элементов в массиве TraceGuidReg . Если traceGuidReg имеет значение NULL, задайте для этого параметра значение 0.
[in, out] TraceGuidReg
Указатель на массив
TRACE_GUID_REGISTRATION структуры.
Каждый элемент определяет категорию событий, которые предоставляет поставщик.
На входных данных член GUID каждой структуры содержит GUID класса трассировки событий, назначенный регистрирующим поставщиком. GUID класса идентифицирует категорию событий, которые предоставляет поставщик. Поставщики используют один и тот же GUID класса для задания элемента Guid EVENT_TRACE_HEADER при вызове функции TraceEvent для регистрации события.
В выходных данных член RegHandle получает дескриптор регистрации GUID класса события. Если поставщик вызывает функцию TraceEventInstance , используйте элемент RegHandleTRACE_GUID_REGISTRATION , чтобы задать элемент RegHandleEVENT_INSTANCE_HEADER.
Этот параметр может иметь значение NULL , если поставщик вызывает только функцию TraceEvent для регистрации событий. Если поставщик вызывает функцию TraceEventInstance для регистрации событий, этот параметр не может иметь значение NULL.
[in] MofImagePath
Этот параметр не поддерживается. Задайте значение NULL. Для регистрации ресурса MOF во время настройки приложения следует использовать Mofcomp.exe. Дополнительные сведения см. в статье Публикация схемы событий.
Windows XP с пакетом обновления 1 (SP1), Windows XP и Windows 2000: Указатель на необязательную строку, указывающую путь к библиотеке DLL или исполняемой программе, содержащей ресурс, указанный в MofResourceName. Этот параметр может иметь значение NULL , если поставщик событий и потребитель используют другой механизм для совместного использования сведений о классах трассировки событий, используемых поставщиком.
[in] MofResourceName
Этот параметр не поддерживается. Задайте значение NULL. Для регистрации ресурса MOF во время настройки приложения следует использовать Mofcomp.exe. Дополнительные сведения см. в статье Публикация схемы событий.
Windows XP с пакетом обновления 1 (SP1), Windows XP и Windows 2000: Указатель на необязательную строку, указывающую строковый ресурс MofImagePath. Строковый ресурс содержит имя двоичного MOF-файла, описывающего классы трассировки событий, поддерживаемые поставщиком.
[out] RegistrationHandle
Получает дескриптор регистрации поставщика. Используйте возвращенный дескриптор при вызове функции UnregisterTraceGuids .
Важно!
Все дескрипторы регистрации, созданные библиотекой DLL или драйвером, должны быть отменены до выгрузки библиотеки DLL или драйвера. Если поставщик не отменен, произойдет сбой при попытке трассировки событий Windows вызвать обратный вызов поставщика.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.
Важно!
Эта функция также может возвращать значение, возвращаемое ControlCallback , если контроллер вызывает EnableTrace для включения поставщика, а поставщик еще не вызвал RegisterTraceGuids. В этом случае RegisterTraceGuids вернет возвращаемое значение обратного вызова, если регистрация прошла успешно.
ERROR_INVALID_PARAMETER
Выполняется одно из следующих условий.
- RequestAddress имеет значение NULL.
- ControlGuid имеет значение NULL.
- RegistrationHandle имеет значение NULL.
Windows XP и Windows 2000:TraceGuidReg имеет значение NULL или GuidCount меньше или равно нулю.
Комментарии
Примечание
Большинство разработчиков не будут вызывать эту функцию напрямую. Вместо этого разработчики обычно используют платформу трассировки событий Windows. Например, WPP на основе TMF управляет вызовами RegisterTraceGuids, TraceMessage и UnregisterTraceGuids от вашего имени.
Эта функция открывает дескриптор поставщика классических событий (в стиле Windows 2000), который можно использовать для записи событий ТРАССИРОВКИ СОБЫТИЙ WPP на основе MOF и TMF с помощью TraceEvent, TraceEventInstance, TraceMessage и TraceMessageVa.
Примечание
Чтобы открыть дескриптор поставщика в стиле Windows Vista , который записывает события трассировки событий Windows на основе манифеста или TraceLogging через EventWrite, используйте EventRegister.
Если controlGuid поставщика был ранее зарегистрирован и включен, последующие регистрации, ссылающиеся на тот же ControlGuid , включаются автоматически.
Процесс может зарегистрировать до 1024 GUID поставщика; однако следует ограничить количество поставщиков, регистрируемого процессом, одним или двумя. Это ограничение включает тех, кто зарегистрирован с помощью этой функции и функции EventRegister .
До Windows Vista: Количество поставщиков, которые может зарегистрировать процесс, не ограничено.
Примеры
Пример использования RegisterTraceGuids см. в разделе Написание классических событий.
Примечание
Заголовок evntrace.h определяет RegisterTraceGuids в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по