TdhCreatePayloadFilter 関数 (tdh.h)
TdhCreatePayloadFilter 関数は、EnableTraceEx2 関数で使用する 1 つのペイロードに対して 1 つのフィルターを作成します。
構文
TDHSTATUS TdhCreatePayloadFilter(
[in] LPCGUID ProviderGuid,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] BOOLEAN EventMatchANY,
[in] ULONG PayloadPredicateCount,
[in] PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
[out] PVOID *PayloadFilter
);
パラメーター
[in] ProviderGuid
EventDescriptor パラメーターのマニフェスト プロバイダーを識別する GUID。
[in] EventDescriptor
ペイロードがフィルター処理されるイベント記述子へのポインター。
[in] EventMatchANY
複数の条件が指定された場合のイベントの処理方法を示すブール値。
このパラメーターが TRUE の場合、フィルターで指定された条件のいずれかが TRUE の場合、イベントがセッションに書き込まれます。
このパラメーターが FALSE の場合、フィルターで指定されたすべての条件が TRUE の場合にのみ、イベントがセッションに書き込まれます。
[in] PayloadPredicateCount
フィルターで指定された条件の数。 この値は、Tdh.h ヘッダー ファイルで定義されているETW_MAX_PAYLOAD_PREDICATES定数以下である必要があります。
[in] PayloadPredicates
フィルターが指定するリスト条件 を 含むPAYLOAD_FILTER_PREDICATE構造体の配列へのポインター。
[out] PayloadFilter
成功すると、このパラメーターは、指定された条件に合わせて適切なサイズとビルドが行われる 1 つのペイロード フィルターへのポインターを返します。
呼び出し元が EnableTraceEx2 関数で返されたペイロード フィルターを使用して終了したら、割り当てられたメモリを解放するために TdhDeletePayloadFilter 関数を呼び出す必要があります。
戻り値
成功した場合 は、ERROR_SUCCESS を返します。 それ以外の場合、この関数は、他の戻りコードに加えて、次のいずれかのリターン コードを返します。
| リターン コード | 説明 |
|---|---|
|
プロバイダーのメタデータが見つかりませんでした。 |
|
1 つ以上のパラメーターが無効です。 |
|
結果のペイロード フィルターは、ペイロード内の EVENT_FILTER_DESCRIPTOR 構造体に 対して EnableTraceEx2 関数によって課される MAX_EVENT_FILTER_PAYLOAD_SIZE 制限内に収まりません。 |
|
ペイロード フィルターを作成するためにメモリを割り当てられません。 |
|
指定されたプロバイダー GUID のスキーマ情報が見つかりませんでした。 |
解説
Windows 8.1、Windows Server 2012 R2 以降では、EnableTraceEx2 関数でイベント ペイロード フィルターを使用して、ロガー セッション内のイベントの特定のコンテンツをフィルター処理できます。
TdhCreatePayloadFilter 関数は、EnableTraceEx2 関数で使用される 1 つのペイロードの単一のペイロード フィルターを作成するために使用されます。 TdhCreatePayloadFilter は、単一のペイロード フィルターに対して不透明なデータ構造を割り当てて入力します。 ペイロード フィルターが不要になった場合、 TdhDeletePayloadFilter 関数を使用して、ペイロード フィルターに割り当てられたメモリを解放します。
1 つのプロバイダーの場合、複数のイベントに個別のペイロード フィルターを設定できます。 また、同じイベントに対して複数のフィルターを使用することもできます。ペイロードは、イベントのフィルターの一部またはすべてが渡された場合にセッションに渡されます。
EnableTraceEx2 関数は、EnableParameters パラメーターで渡されたENABLE_TRACE_PARAMETERS構造体のEVENT_FILTER_DESCRIPTOR構造体の配列を受け取ります。 配列には、イベント フィルターの種類ごとに 1 つのエントリしか存在できません。 TdhAggregatePayloadFilters 関数を使用すると、TdhCreatePayloadFilter を使用して作成された 1 つのプロバイダーのペイロード フィルターの一覧を 1 つのデータ構造に集計し、EnableTraceEx2 関数で使用するEVENT_FILTER_DESCRIPTORを返すことができます。
例
TdhCreatePayloadFilter 関数を使用して、ロガー セッションの特定の条件に対するフィルター処理に使用するペイロード フィルターを作成する例については、EnableTraceEx2 関数の例を参照してください。
要件
| サポートされている最小のクライアント | Windows 8.1 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2012 R2 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | tdh.h |
| Library | Tdh.lib |
| [DLL] | Tdh.dll |