次の方法で共有


EtwWrite 関数 (wdm.h)

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、EtwWriteExEtwWriteStringEtwWriteTransfer 関数に渡されるデータはページングできません。 つまり、APC_LEVELより大きい IRQL で実行されているカーネル モード ルーチンは、ページング可能なメモリにアクセスできません。 EtwWrite、EtwWriteExEtwWriteString、および 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 任意のレベル (「コメント」セクションを参照)。

こちらもご覧ください

EtwEventEnabled

EtwProviderEnabled

EtwRegister

EtwUnregister

EtwWriteEx

EtwWriteString

EtwWriteTransfer

EventDataDescCreate