ホーム › System.Diagnostics.Etw › TdhCreatePayloadFilter

TdhCreatePayloadFilter

関数

イベントペイロードに基づくフィルターを作成する。

DLLTDH.dll呼出規約winapi対応OSWindows 8.1 以降

シグネチャ

// TDH.dll
#include <windows.h>

DWORD TdhCreatePayloadFilter(
    const GUID* ProviderGuid,
    const EVENT_DESCRIPTOR* EventDescriptor,
    BOOLEAN EventMatchANY,
    DWORD PayloadPredicateCount,
    PAYLOAD_FILTER_PREDICATE* PayloadPredicates,
    void** PayloadFilter
);

パラメーター

名前	型	方向	説明
ProviderGuid	GUID*	in	EventDescriptor パラメーターのマニフェストプロバイダーを識別する GUID。
EventDescriptor	EVENT_DESCRIPTOR*	in	ペイロードがフィルター処理されるイベント記述子へのポインター。
EventMatchANY	BOOLEAN	in	複数の条件が指定された場合にイベントをどのように処理するかを示すブール値。このパラメーターが TRUE の場合、フィルターで指定された条件のいずれかが TRUE であれば、イベントはセッションに書き込まれます。このパラメーターが FALSE の場合、フィルターで指定されたすべての条件が TRUE である場合にのみ、イベントはセッションに書き込まれます。
PayloadPredicateCount	DWORD	in	フィルターで指定された条件の数。この値は、Tdh.h ヘッダーファイルで定義されている ETW_MAX_PAYLOAD_PREDICATES 定数以下である必要があります。
PayloadPredicates	PAYLOAD_FILTER_PREDICATE*	in	フィルターが指定する条件のリストを含む PAYLOAD_FILTER_PREDICATE 構造体の配列へのポインター。
PayloadFilter	void**	out	成功した場合、このパラメーターは、指定された条件に対して適切なサイズで構築された単一のペイロードフィルターへのポインターを返します。返されたペイロードフィルターを EnableTraceEx2 関数で使用し終えたら、TdhDeletePayloadFilter 関数を呼び出して、割り当てられたメモリを解放してください。

戻り値の型: DWORD

公式ドキュメント

EnableTraceEx2 関数で使用する、単一ペイロードに対する単一フィルターを作成します。

戻り値

成功した場合は ERROR_SUCCESS を返します。それ以外の場合、この関数はその他のコードに加えて、次のいずれかの戻りコードを返します。

戻りコード	説明
ERROR_FILE_NOT_FOUND	プロバイダーのメタデータが見つかりませんでした。
ERROR_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。
ERROR_INSUFFICIENT_BUFFER	生成されるペイロードフィルターが、EnableTraceEx2 関数によってペイロード内の EVENT_FILTER_DESCRIPTOR 構造体に課される MAX_EVENT_FILTER_PAYLOAD_SIZE の制限に収まりません。
ERROR_NOT_ENOUGH_MEMORY	ペイロードフィルターを作成するためのメモリを割り当てられませんでした。
ERROR_NOT_FOUND	指定されたプロバイダー GUID のスキーマ情報が見つかりませんでした。

解説(Remarks)

Windows 8.1、Windows Server 2012 R2 以降では、EnableTraceEx2 関数でイベントペイロードフィルターを使用して、ロガーセッション内のイベントの特定の内容に基づいてフィルター処理できます。

TdhCreatePayloadFilter 関数は、EnableTraceEx2 関数で使用する、単一ペイロードに対する単一のペイロードフィルターを作成するために使用します。TdhCreatePayloadFilter は、単一のペイロードフィルター用の不透明なデータ構造を割り当てて設定します。ペイロードフィルターが不要になったら、TdhDeletePayloadFilter 関数を使用して、ペイロードフィルターに割り当てられたメモリを解放します。

1 つのプロバイダーに対して、複数のイベントが個別のペイロードフィルターを持つことができます。また、同じイベントに対して複数のフィルターを設定することもでき、イベントのフィルターのいずれか、またはすべてがペイロードを通過させた場合に、そのペイロードがセッションに渡されます。

EnableTraceEx2 関数は、EnableParameters パラメーターで渡される ENABLE_TRACE_PARAMETERS 構造体内の EVENT_FILTER_DESCRIPTOR 構造体の配列を受け取ります。各イベントフィルタータイプにつき、配列内のエントリは 1 つだけです。TdhAggregatePayloadFilters 関数を使用すると、TdhCreatePayloadFilter を使用して作成した単一プロバイダーのペイロードフィルターのリストを 1 つのデータ構造に集約し、EnableTraceEx2 関数で使用する EVENT_FILTER_DESCRIPTOR を返すことができます。

例

ロガーセッションで特定の条件に基づいてフィルター処理を行うためのペイロードフィルターを TdhCreatePayloadFilter 関数を使用して作成する例については、EnableTraceEx2 関数の例を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// TDH.dll
#include <windows.h>

DWORD TdhCreatePayloadFilter(
    const GUID* ProviderGuid,
    const EVENT_DESCRIPTOR* EventDescriptor,
    BOOLEAN EventMatchANY,
    DWORD PayloadPredicateCount,
    PAYLOAD_FILTER_PREDICATE* PayloadPredicates,
    void** PayloadFilter
);

[DllImport("TDH.dll", ExactSpelling = true)]
static extern uint TdhCreatePayloadFilter(
    ref Guid ProviderGuid,   // GUID*
    IntPtr EventDescriptor,   // EVENT_DESCRIPTOR*
    [MarshalAs(UnmanagedType.U1)] bool EventMatchANY,   // BOOLEAN
    uint PayloadPredicateCount,   // DWORD
    IntPtr PayloadPredicates,   // PAYLOAD_FILTER_PREDICATE*
    IntPtr PayloadFilter   // void** out
);

<DllImport("TDH.dll", ExactSpelling:=True)>
Public Shared Function TdhCreatePayloadFilter(
    ByRef ProviderGuid As Guid,   ' GUID*
    EventDescriptor As IntPtr,   ' EVENT_DESCRIPTOR*
    <MarshalAs(UnmanagedType.U1)> EventMatchANY As Boolean,   ' BOOLEAN
    PayloadPredicateCount As UInteger,   ' DWORD
    PayloadPredicates As IntPtr,   ' PAYLOAD_FILTER_PREDICATE*
    PayloadFilter As IntPtr   ' void** out
) As UInteger
End Function

' ProviderGuid : GUID*
' EventDescriptor : EVENT_DESCRIPTOR*
' EventMatchANY : BOOLEAN
' PayloadPredicateCount : DWORD
' PayloadPredicates : PAYLOAD_FILTER_PREDICATE*
' PayloadFilter : void** out
Declare PtrSafe Function TdhCreatePayloadFilter Lib "tdh" ( _
    ByVal ProviderGuid As LongPtr, _
    ByVal EventDescriptor As LongPtr, _
    ByVal EventMatchANY As Byte, _
    ByVal PayloadPredicateCount As Long, _
    ByVal PayloadPredicates As LongPtr, _
    ByVal PayloadFilter As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

TdhCreatePayloadFilter = ctypes.windll.tdh.TdhCreatePayloadFilter
TdhCreatePayloadFilter.restype = wintypes.DWORD
TdhCreatePayloadFilter.argtypes = [
    ctypes.c_void_p,  # ProviderGuid : GUID*
    ctypes.c_void_p,  # EventDescriptor : EVENT_DESCRIPTOR*
    wintypes.BOOLEAN,  # EventMatchANY : BOOLEAN
    wintypes.DWORD,  # PayloadPredicateCount : DWORD
    ctypes.c_void_p,  # PayloadPredicates : PAYLOAD_FILTER_PREDICATE*
    ctypes.c_void_p,  # PayloadFilter : void** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('TDH.dll')
TdhCreatePayloadFilter = Fiddle::Function.new(
  lib['TdhCreatePayloadFilter'],
  [
    Fiddle::TYPE_VOIDP,  # ProviderGuid : GUID*
    Fiddle::TYPE_VOIDP,  # EventDescriptor : EVENT_DESCRIPTOR*
    Fiddle::TYPE_CHAR,  # EventMatchANY : BOOLEAN
    -Fiddle::TYPE_INT,  # PayloadPredicateCount : DWORD
    Fiddle::TYPE_VOIDP,  # PayloadPredicates : PAYLOAD_FILTER_PREDICATE*
    Fiddle::TYPE_VOIDP,  # PayloadFilter : void** out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "tdh")]
extern "system" {
    fn TdhCreatePayloadFilter(
        ProviderGuid: *const GUID,  // GUID*
        EventDescriptor: *const EVENT_DESCRIPTOR,  // EVENT_DESCRIPTOR*
        EventMatchANY: u8,  // BOOLEAN
        PayloadPredicateCount: u32,  // DWORD
        PayloadPredicates: *mut PAYLOAD_FILTER_PREDICATE,  // PAYLOAD_FILTER_PREDICATE*
        PayloadFilter: *mut *mut ()  // void** out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("TDH.dll")]
public static extern uint TdhCreatePayloadFilter(ref Guid ProviderGuid, IntPtr EventDescriptor, [MarshalAs(UnmanagedType.U1)] bool EventMatchANY, uint PayloadPredicateCount, IntPtr PayloadPredicates, IntPtr PayloadFilter);
"@
$api = Add-Type -MemberDefinition $sig -Name 'TDH_TdhCreatePayloadFilter' -Namespace Win32 -PassThru
# $api::TdhCreatePayloadFilter(ProviderGuid, EventDescriptor, EventMatchANY, PayloadPredicateCount, PayloadPredicates, PayloadFilter)

#uselib "TDH.dll"
#func global TdhCreatePayloadFilter "TdhCreatePayloadFilter" sptr, sptr, sptr, sptr, sptr, sptr
; TdhCreatePayloadFilter varptr(ProviderGuid), varptr(EventDescriptor), EventMatchANY, PayloadPredicateCount, varptr(PayloadPredicates), PayloadFilter   ; 戻り値は stat
; ProviderGuid : GUID* -> "sptr"
; EventDescriptor : EVENT_DESCRIPTOR* -> "sptr"
; EventMatchANY : BOOLEAN -> "sptr"
; PayloadPredicateCount : DWORD -> "sptr"
; PayloadPredicates : PAYLOAD_FILTER_PREDICATE* -> "sptr"
; PayloadFilter : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "TDH.dll"
#cfunc global TdhCreatePayloadFilter "TdhCreatePayloadFilter" var, var, int, int, var, sptr
; res = TdhCreatePayloadFilter(ProviderGuid, EventDescriptor, EventMatchANY, PayloadPredicateCount, PayloadPredicates, PayloadFilter)
; ProviderGuid : GUID* -> "var"
; EventDescriptor : EVENT_DESCRIPTOR* -> "var"
; EventMatchANY : BOOLEAN -> "int"
; PayloadPredicateCount : DWORD -> "int"
; PayloadPredicates : PAYLOAD_FILTER_PREDICATE* -> "var"
; PayloadFilter : void** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "TDH.dll"
#cfunc global TdhCreatePayloadFilter "TdhCreatePayloadFilter" sptr, sptr, int, int, sptr, sptr
; res = TdhCreatePayloadFilter(varptr(ProviderGuid), varptr(EventDescriptor), EventMatchANY, PayloadPredicateCount, varptr(PayloadPredicates), PayloadFilter)
; ProviderGuid : GUID* -> "sptr"
; EventDescriptor : EVENT_DESCRIPTOR* -> "sptr"
; EventMatchANY : BOOLEAN -> "int"
; PayloadPredicateCount : DWORD -> "int"
; PayloadPredicates : PAYLOAD_FILTER_PREDICATE* -> "sptr"
; PayloadFilter : void** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。