EtwWriteEx 関数 (wdm.h)
EtwWriteEx 関数は、カーネル モード ドライバー コードでのフィルター処理をサポートするイベントを発行するためのトレース関数です。
構文
NTSTATUS EtwWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
パラメーター
[in] RegHandle
イベント プロバイダー登録ハンドルへのポインター。イベント プロバイダーの登録が成功した場合に EtwRegister 関数によって返されます。
[in] EventDescriptor
EVENT_DESCRIPTOR構造体へのポインター。
[in] Filter
イベントが書き込まれないようにするセッションを識別するインスタンス識別子。 つまり、値はセッションのマスクであり、ログ記録から除外する必要があります (除外)。 複数の識別子を指定するには、ビットごとの OR を使用します。 フィルターをサポートしていない場合、またはイベントがすべてのセッションに書き込まれている場合は、0 に設定します (フィルターは失敗しません)。 セッションの識別子を取得する方法については、EtwEnableCallback コールバックの FilterData パラメーターを参照してください。
[in] Flags
予約済み。 0 (0) にする必要があります。
[in, optional] ActivityId
イベントに関連付けられているアクティビティを示す識別子。 ActivityID は、関連するイベントをグループ化する方法を提供し、エンドツーエンドのトレースで使用されます。 NULL の場合、ETW はスレッド ローカル ストレージから識別子を取得します。 この識別子の取得の詳細については、「 EtwActivityIdControl」を参照してください。
[in, optional] RelatedActivityId
直前のコンポーネントからの動作識別子。 このパラメーターを使用して、特定のコンポーネントのイベントを直前のコンポーネントのイベントにリンクさせます。 前のコンポーネントに設定されたアクティビティ識別子を取得するには、EtwActivityIdControl 関数の ControlCode パラメーターの説明を参照してください。
[in] UserDataCount
UserData 内のEVENT_DATA_DESCRIPTOR構造体の数。 最大数は 128 です。
[in, optional] UserData
構造体の配列へのポインター EVENT_DATA_DESCRIPTOR。 UserDataCount が 0 の場合は、このパラメーターを NULL に設定します。 データは、マニフェストに指定された順序で格納されている必要があります。
戻り値
成功した場合はERROR_SUCCESSを返し、エラー時には次のいずれかの値を返します。
注釈
EtwWriteEx 関数は、ユーザー モード EventWriteEx 関数と同等のカーネル モードです。 この関数で書き込まれたイベント データにはマニフェストが必要です。 マニフェストはプロバイダーに埋め込まれているため、コンシューマーがデータを使用するにはプロバイダーを使用できる必要があります。 発行するイベントのコンシューマーが存在することを確認するには、 EtwWrite の呼び出しの前に EtwEventEnabled または EtwProviderEnabled を呼び出します。
エンドツーエンドのトレース シナリオでさまざまなコンポーネントのイベントを関連付ける場合は、 ActivityId パラメーターと RelatedActivityId パラメーターを使用します。 たとえば、コンポーネント A、B、C は関連するアクティビティに対して作業を実行し、コンシューマーがそのアクティビティに関連するすべてのイベントを使用できるようにイベントをリンクしたいとします。
任意の IRQL で EtwWriteEx を 呼び出すことができます。 ただし、IRQL がAPC_LEVELより大きい場合、EtwWrite、EtwWriteEx、EtwWriteString、EtwWriteTransfer 関数に渡されるデータはページングできません。 つまり、APC_LEVELより大きい IRQL で実行されているカーネル モード ルーチンは、ページング可能なメモリにアクセスできません。 EtwWrite、EtwWriteEx、EtwWriteString、および EtwWriteTransfer 関数に渡されるデータは、IRQL とは関係なく、システム空間メモリ内に存在する必要があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 7 |
| サポートされている最小のサーバー | Windows Server 2008 R2 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |