EtwWrite 関数 (wdm.h)

[アーティクル]
03/05/2024

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 カウンターは、記録されなかったイベントの数で更新されます。

注釈

EtwWrite 関数は、ユーザーモード EventWrite 関数と同等のカーネルモードです。発行するイベントのコンシューマーが存在することを確認するには、 EtwWrite の呼び出しの前に EtwEventEnabled または EtwProviderEnabled を呼び出します。

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 とは関係なく、システム空間メモリ内に存在する必要があります。

例

 
 //
 // 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
    }              

//

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	任意のレベル (「コメント」セクションを参照)。