EtwWrite 함수(wdm.h)

아티클
02/06/2022
읽는 데 5분 걸림

EtwWrite 함수는 커널 모드 드라이버 코드에서 이벤트를 게시하기 위한 추적 함수입니다.

구문

NTSTATUS EtwWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

매개 변수

[in] RegHandle

이벤트 공급자 등록에 성공하면 EtwRegister 함수에서 반환되는 이벤트 공급자 등록 핸들에 대한 포인터입니다.

[in] EventDescriptor

EVENT_DESCRIPTOR 구조체에 대한 포인터입니다.

[in, optional] ActivityId

이벤트와 연결된 활동을 나타내는 식별자입니다. ActivityID는 관련 이벤트를 그룹화할 수 있는 방법을 제공하며 엔드 투 엔드 추적에 사용됩니다.

[in] UserDataCount

UserData의 EVENT_DATA_DESCRIPTOR 구조체 수입니다.

[in, optional] UserData

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

반환 값

이벤트가 성공적으로 게시되면 EtwWrite 는 STATUS_SUCCESS 반환합니다.

이벤트 공급자 등록 핸들에 대한 포인터가 유효하지 않으면 EtwWrite 는 STATUS_INVALID_HANDLE 반환합니다. EtwWrite가 호출되기 전에 이벤트 공급자를 등록해야 합니다. EtwWrite 는 이벤트를 기록할 수 없는 경우 STATUS_INVALID_HANDLE 반환할 수도 있습니다.

UserDataCount에 지정된 EVENT_DATA_DESCRIPTOR 구조체 수가 허용되는 최대값(128)보다 크면 EtwWrite는 STATUS_INVALID_PARAMETER 반환합니다.

ActivityID가 지정되었지만 이벤트와 연결된 데이터를 기록하는 데 사용할 수 있는 메모리가 부족한 경우 EtwWrite는 STATUS_NO_MEMORY 반환합니다.

공급자가 세션에 대해 사용하도록 설정되지 않은 경우 EtwWrite 는 STATUS_SUCCESS 반환하고 이벤트는 기록되지 않습니다.

이벤트는 여러 가지 이유로 손실될 수 있습니다. 예를 들어 이벤트 속도가 너무 높거나 이벤트 크기가 버퍼 크기보다 큰 경우입니다. 이러한 경우 해당 로거에 대한 EVENT_TRACE_PROPERTIES 구조의 멤버인 EventsLost 카운터가 기록되지 않은 이벤트 수로 업데이트됩니다.

예제

 
 //
 // Register the provider with ETW in DriverEntry
 // Unregister the provider in DriverUnload 
    //
 //  Build the EVENT_DATA_DESCRIPTOR structures using 
 //   the EventDataDescCreate macros 
 
 if (RegHandle != (REGHANDLE)NULL) {
 //
 // Log an Event with : DeviceNameLength
 //                      DeviceName
 //                      Status
 //
 
 EventDataDescCreate(&EventDataDescriptor[0],
                            (PVOID)&DeviceName.Length,
 sizeof(USHORT));
 

 EventDataDescCreate(&EventDataDescriptor[1],
                            (PVOID)DeviceName.Buffer,
 DeviceName.Length);
 
 EventDataDescCreate(&EventDataDescriptor[2],
                            (PVOID)&Status,
 sizeof(ULONG));
 
 EtwWrite(RegHandle,            // Handle from EtwRegister
                 &StartEvent,          // EventDescriptor
                 NULL,                 // Activity ID
                 3,                    // Number of data items
 EventDataDescriptor); // Array of data descriptors
    }              

//

설명

EtwWrite 함수는 사용자 모드 EventWrite 함수와 동일한 커널 모드입니다. 게시하는 이벤트에 대한 소비자가 있는지 확인하려면 EtwEventEnabled 또는 EtwProviderEnabled에 대한 호출과 함께 EtwWrite 호출 앞에 올 수 있습니다.

EtwWrite 함수를 호출하여 이벤트를 게시하려면 먼저 공급자를 EtwRegister에 등록해야 합니다. EtwRegister 및 EtwUnregister 함수에 의해 바인딩된 코드 외부에 있는 추적 호출은 만들어서는 안 됩니다. 최상의 성능을 위해 DriverEntry 루틴에서 EtwRegister 함수를 호출하고 DriverUnload 루틴에서 EtwUnregister 함수를 호출할 수 있습니다.

EtwWrite 함수에서 선택적 UserData 매개 변수를 사용하여 추가 이벤트 데이터를 기록하는 경우 EventDataDescCreate 매크로를 사용하여 EVENT_DATA_DESCRIPTOR 구조체 만들기를 간소화할 수 있습니다. 다음 예제에서는 EventDataDescCreate 매크로를 사용하여 디바이스 이름과 상태를 사용하여 EVENT_DATA_DESCRIPTOR 구조를 초기화합니다. EventDataDescCreate 매크로는 데이터에 대한 포인터를 저장합니다(즉, 데이터 복사본을 저장하지 않음). EtwWrite 호출이 반환될 때까지 포인터는 유효한 상태를 유지해야 합니다.

모든 IRQL에서 EtwWrite 를 호출할 수 있습니다. 그러나 IRQL이 APC_LEVEL보다 크면 EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer 함수에 전달된 모든 데이터를 페이징할 수 없어야 합니다. 즉, APC_LEVEL보다 큰 IRQL에서 실행되는 커널 모드 루틴은 페이저블 메모리에 액세스할 수 없습니다. EtwWrite, EtwWriteEx, EtwWriteString 및 EtwWriteTransfer 함수에 전달된 데이터는 IRQL이 무엇인지에 관계없이 시스템 공간 메모리에 있어야 합니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista 이상 버전의 Windows 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	모든 수준(설명 섹션 참조)