EventRegister 함수(evntprov.h)
ETW 이벤트 공급자를 등록하여 ETW 이벤트를 작성하는 데 사용할 수 있는 핸들을 만듭니다.
구문
ULONG EVNTAPI EventRegister(
[in] LPCGUID ProviderId,
[in, optional] PENABLECALLBACK EnableCallback,
[in, optional] PVOID CallbackContext,
[out] PREGHANDLE RegHandle
);
매개 변수
[in] ProviderId
공급자를 고유하게 식별하는 GUID(컨트롤 GUID라고도 함). 추적 컨트롤러가 GUID를 사용하여 이 공급자의 이벤트를 구독할 수 있도록 안정적인 식별자여야 합니다.
[in, optional] EnableCallback
추적 세션이 이 공급자를 사용하거나 사용하지 않도록 설정할 때 ETW가 호출하는 선택적 EnableCallback 입니다. 콜백이 필요하지 않은 경우 를 사용합니다 NULL .
[in, optional] CallbackContext
EnableCallback을 호출할 때 ETW에서 제공하는 선택적 컨텍스트 데이터입니다. 콜백 컨텍스트가 필요하지 않은 경우 를 사용합니다 NULL .
[out] RegHandle
이벤트 공급자 등록 핸들을 받습니다. 핸들은 EventWrite, EventProviderEnabled 및 EventRegister와 같은 공급자 API에 대한 후속 호출에 사용됩니다.
공급자가 언로드하거나 종료하기 전에 EventUnregister를 호출하여 공급자 등록 핸들을 해제합니다. 등록된 모든 공급자 핸들을 해제하지 않고 언로드하는 DLL로 인해 프로세스가 충돌할 수 있습니다.
반환 값
성공하면 ERROR_SUCCESS 반환합니다.
EventRegister에서 반환된 오류 코드는 주로 디버깅 및 진단 시나리오에 사용하기 위한 것입니다. ETW 공급자를 등록하지 못한 경우에도 대부분의 프로덕션 코드는 계속 실행되어야 하므로 릴리스 빌드는 일반적으로 EventRegister에서 반환된 오류 코드를 무시해야 합니다.
설명
EventRegister는 EventWrite, EventWriteTransfer 또는 EventWriteEx를 통해 ETW 이벤트를 작성하는 데 사용할 수 있는 핸들을 만듭니다.
참고
대부분의 이벤트 공급자는 EventRegister 를 직접 호출하지 않습니다. 대신 대부분의 이벤트 공급자는 EventRegister, EventWrite 및 EventUnregister에 대한 호출을 래핑하는 ETW 프레임워크를 사용하여 구현됩니다. 예를 들어 이벤트 매니페스트를 작성한 다음 메시지 컴파일러 를 사용하여 이벤트에 대한 C/C++ 코드를 생성하거나 TraceLogging 을 사용하여 매니페스트가 필요하지 않을 수 있습니다.
이벤트 공급자 등록은 이벤트 공급자의 매니페스트 설치와 혼동해서는 안 됩니다.
- EventRegister API는 이벤트 공급자 등록을 수행하여 공급자 핸들을 만듭니다. 프로세스 scope 작업입니다(핸들은 프로세스 내에서만 유효). 핸들을 사용하여 ETW 이벤트를 작성할 수 있습니다. 핸들을 사용하여 작성된 모든 이벤트는 공급자 등록 중에 지정된 ProviderId 로 태그가 지정됩니다. 이벤트를 작성하거나 추적을 캡처하기 위해 매니페스트를 설치할 필요는 없습니다(공급자의 이벤트를 디코딩하거나 공급자가 이벤트 로그를 사용하려면 매니페스트를 설치해야 할 수 있음).
- wevtutil.exe 도구는 이벤트 공급자의 매니페스트를 설치하거나 제거하는 데 사용됩니다. 이벤트 공급자 매니페스트를 설치하면 매니페스트의 정보가 시스템에 기록됩니다. 기록된 정보는 시스템 전역이며 매니페스트가 제거될 때까지 유지됩니다. 기록된 정보에는 매니페스트에 정의된 공급자의 이름, GUID, 채널 및 리소스 DLL 경로가 포함됩니다. 매니페스트의 정보는 추적 디코딩 도구 및 이벤트 로그에서 사용됩니다.
대부분의 구성 요소는 구성 요소 초기화 시 이벤트 공급자를 등록하고 구성 요소 종료 시 이벤트 공급자의 등록을 취소합니다. 예를 들어 애플리케이션(EXE)은 애플리케이션을 시작하는 동안 등록하고 애플리케이션 종료 중에 등록을 취소할 수 있습니다. DLL(동적 라이브러리)은 프로세스 연결 중에 등록 DllMain 될 수 있으며 프로세스 분리 중에 등록 DllMain 을 취소할 수 있습니다.
이벤트 추적은 디버깅/진단 문제이며 일반적으로 애플리케이션에 중요한 기능이 아니기 때문에 대부분의 소매 애플리케이션은 EventRegister에서 반환된 오류를 자동으로 무시해야 합니다. 오류가 발생할 경우 EventRegister 는 RegHandle 매개 변수를 0으로 설정하므로 RegHandle의 후속 사용(예: EventWrite 및 EventUnregister 호출)이 적용되지 않습니다.
각 프로세스는 최대 1,024개의 공급자를 등록할 수 있습니다. 그러나 구성 요소가 등록하는 공급자 수를 한두 개로 제한해야 합니다. 이 제한에는 이 함수를 사용하여 등록된 공급자와 RegisterTraceGuids를 사용하여 등록된 공급자가 포함됩니다.
Windows Vista 이전: 프로세스가 등록할 수 있는 공급자 수에 대한 특정 제한은 없습니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntprov.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |