次の方法で共有


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 を返します。 それ以外の場合、この関数は、他の戻りコードに加えて、次のいずれかのリターン コードを返します。

リターン コード 説明
ERROR_FILE_NOT_FOUND
プロバイダーのメタデータが見つかりませんでした。
ERROR_INVALID_PARAMETER
1 つ以上のパラメーターが無効です。
ERROR_INSUFFICIENT_BUFFER
結果のペイロード フィルターは、ペイロード内の EVENT_FILTER_DESCRIPTOR 構造体に 対して EnableTraceEx2 関数によって課される MAX_EVENT_FILTER_PAYLOAD_SIZE 制限内に収まりません。
ERROR_NOT_ENOUGH_MEMORY
ペイロード フィルターを作成するためにメモリを割り当てられません。
ERROR_NOT_FOUND
指定されたプロバイダー 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

関連項目

ENABLE_TRACE_PARAMETERS

EVENT_DESCRIPTOR

EVENT_FILTER_DESCRIPTOR

EnableTraceEx2

PAYLOAD_FILTER_PREDICATE

TdhAggregatePayloadFilters

TdhCleanupPayloadEventFilterDescriptor

TdhDeletePayloadFilter