RegisterTraceGuidsA 함수(evntrace.h)

  • 아티클

RegisterTraceGuids 함수는 클래식(Windows 2000 스타일) ETW 이벤트 추적 공급자 및 이벤트를 생성하는 데 사용하는 이벤트 추적 클래스를 등록합니다. 또한 이 함수는 시스템에서 공급자로부터 추적을 사용하거나 사용하지 않도록 설정하는 데 사용하는 콜백 함수를 지정합니다.

이 함수는 사용되지 않습니다. 새 코드 는 EventRegister 를 사용하여 Windows Vista 스타일 (Crimson) ETW 이벤트 추적 공급자를 등록해야 합니다.

구문

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

ETW가 RequestAddress에서 지정한 함수에 전달하는 선택적 공급자 정의 컨텍스트에 대한 포인터입니다.

[in] ControlGuid

등록 공급자의 제어 GUID(공급자 ID)입니다.

[in] GuidCount

TraceGuidReg 배열의 요소 수입니다. TraceGuidReg가 NULL인 경우 이 매개 변수를 0으로 설정합니다.

[in, out] TraceGuidReg

배열에 대한 포인터
TRACE_GUID_REGISTRATION 구조체입니다.

각 요소는 공급자가 제공하는 이벤트의 범주를 식별합니다.

입력 시 각 구조체의 Guid 멤버에는 등록 공급자가 할당한 이벤트 추적 클래스 GUID가 포함됩니다. 클래스 GUID는 공급자가 제공하는 이벤트의 범주를 식별합니다. 공급자는 동일한 클래스 GUID를 사용하여 TraceEvent 함수를 호출하여 이벤트를 기록할 때 EVENT_TRACE_HEADER Guid 멤버를 설정합니다.

출력 시 RegHandle 멤버는 이벤트의 클래스 GUID 등록에 대한 핸들을 받습니다. 공급자가 TraceEventInstance 함수를 호출하는 경우 TRACE_GUID_REGISTRATIONRegHandle 멤버를 사용하여 EVENT_INSTANCE_HEADERRegHandle 멤버를 설정합니다.

공급자가 TraceEvent 함수만 호출하여 이벤트를 기록하는 경우 이 매개 변수는 NULL일 수 있습니다. 공급자가 TraceEventInstance 함수를 호출하여 이벤트를 기록하는 경우 이 매개 변수는 NULL일 수 없습니다.

[in] MofImagePath

이 매개 변수는 지원되지 않습니다. NULL로 설정합니다. Mofcomp.exe 사용하여 애플리케이션을 설정하는 동안 MOF 리소스를 등록해야 합니다. 자세한 내용은 이벤트 스키마 게시를 참조하세요.

WINDOWS XP SP1, Windows XP 및 Windows 2000:MofResourceName에서 지정한 리소스를 포함하는 DLL 또는 실행 프로그램의 경로를 지정하는 선택적 문자열에 대한 포인터입니다. 이벤트 공급자와 소비자가 다른 메커니즘을 사용하여 공급자가 사용하는 이벤트 추적 클래스에 대한 정보를 공유하는 경우 이 매개 변수는 NULL 일 수 있습니다.

[in] MofResourceName

이 매개 변수는 지원되지 않습니다. NULL로 설정합니다. Mofcomp.exe 사용하여 애플리케이션을 설정하는 동안 MOF 리소스를 등록해야 합니다. 자세한 내용은 이벤트 스키마 게시를 참조하세요.

WINDOWS XP SP1, Windows XP 및 Windows 2000:MofImagePath의 문자열 리소스를 지정하는 선택적 문자열에 대한 포인터입니다. 문자열 리소스에는 공급자가 지원하는 이벤트 추적 클래스를 설명하는 이진 MOF 파일의 이름이 포함됩니다.

[out] RegistrationHandle

공급자의 등록 핸들을 받습니다. UnregisterTraceGuids 함수를 호출할 때 반환된 핸들을 사용합니다.

중요

DLL 또는 드라이버에서 만든 모든 등록 핸들은 DLL 또는 드라이버가 언로드되기 전에 등록을 취소해야 합니다. 공급자가 등록 취소되지 않은 경우 ETW가 공급자의 콜백을 호출하려고 할 때 충돌이 발생합니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.

중요

 컨트롤러가 EnableTrace를 호출하여 공급자를 사용하도록 설정하고 공급자가 RegisterTraceGuids를 아직 호출하지 않은 경우 이 함수는 ControlCallback에서 반환된 값을 반환할 수도 있습니다. 이 경우 RegisterTraceGuids 는 등록에 성공하면 콜백의 반환 값을 반환합니다.

  • ERROR_INVALID_PARAMETER

    다음 중 하나에 해당합니다.

    • RequestAddress 가 NULL입니다.
    • ControlGuid 가 NULL입니다.
    • RegistrationHandle 은 NULL입니다.

    Windows XP 및 Windows 2000:TraceGuidReg 가 NULL 이거나 GuidCount 가 0보다 작거나 같습니다.

설명

참고

대부분의 개발자는 이 함수를 직접 호출하지 않습니다. 대신 개발자는 일반적으로 ETW 프레임워크를 사용합니다. 예를 들어 TMF 기반 WPP는 사용자를 대신하여 RegisterTraceGuids, TraceMessage 및 UnregisterTraceGuids 에 대한 호출을 관리합니다.

이 함수는 TraceEvent, TraceEventInstance, TraceMessage 및 TraceMessageVa를 통해 MOF 및 TMF 기반 WPP ETW 이벤트를 작성하는 데 사용할 수 있는 클래식(Windows 2000 스타일) 이벤트 공급자 핸들을 엽니다.

참고

EventWrite를 통해 매니페스트 기반 또는 TraceLogging 기반 ETW 이벤트를 작성하는 Windows Vista 스타일 공급자 핸들을 열려면 EventRegister를 사용합니다.

공급자의 ControlGuid 가 이전에 등록되고 사용하도록 설정된 경우 동일한 ControlGuid 를 참조하는 후속 등록이 자동으로 사용하도록 설정됩니다.

프로세스는 최대 1,024개의 공급자 GUID를 등록할 수 있습니다. 그러나 프로세스가 등록하는 공급자 수를 한두 개로 제한해야 합니다. 이 제한에는 이 함수 및 EventRegister 함수를 사용하여 등록된 제한이 포함됩니다.

Windows Vista 이전: 프로세스가 등록할 수 있는 공급자 수에는 제한이 없습니다.

예제

RegisterTraceGuids를 사용하는 예제는 클래식 이벤트 작성을 참조하세요.

참고

evntrace.h 헤더는 REGISTERTraceGuids를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

   
지원되는 최소 클라이언트 Windows 2000 Professional [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows 2000 Server [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 evntrace.h
라이브러리 Windows 8.1 및 Windows Server 2012 R2의 Sechost.lib; Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.lib
DLL Windows 8.1 및 Windows Server 2012 R2의 Sechost.dll, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.dll

추가 정보

EnableTrace

UnregisterTraceGuids