EVENT_FILTER_DESCRIPTOR 結構 (evntprov.h)

發行項
08/23/2023

EVENT_FILTER_DESCRIPTOR結構會定義會話傳遞至提供者啟用回呼函式的篩選準則資料。

語法

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

成員

Ptr

類型 成員中所 指定之篩選類型的篩選資料的指標。

如果 Type 成員設定為 EVENT_FILTER_TYPE_PID， Ptr 成員會指向 (PID) 的進程識別碼陣列。

如果 Type 成員設定為 EVENT_FILTER_TYPE_EVENT_ID， Ptr 成員會指向包含事件識別碼陣列的 EVENT_FILTER_EVENT_ID 結構，以及判斷指定事件識別碼的追蹤是否已啟用或停用的布林值。

如果 Type 成員設定為 EVENT_FILTER_TYPE_STACKWALK， Ptr 成員會指向包含事件識別碼陣列的 EVENT_FILTER_EVENT_ID 結構，以及判斷指定事件識別碼的堆疊追蹤是否已啟用或停用的布林值。

如果 Type 成員設定為 EVENT_FILTER_TYPE_SCHEMATIZED，請參閱 EVENT_FILTER_HEADER 結構，以取得建構篩選的詳細資料。

Size

資料的大小，以位元組為單位。

資料大小上限會根據指定的 Type 成員而有所不同， (篩選) 的類型。許多篩選類型的資料大小上限限制為 MAX_EVENT_FILTER_DATA_SIZE，在 evntprov.h 標頭檔中定義為 1024。

Type

識別篩選準則的提供者定義值。針對檢測資訊清單中定義的篩選，請將此成員設定為 EVENT_FILTER_TYPE_SCHEMATIZED。

這個成員的可能值定義在 evntprov.h 標頭檔中。

EVENT_FILTER_TYPE_NONE (0x00000000)

沒有篩選。
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

架構化篩選準則。

這是傳統的篩選設定，也稱為提供者端篩選。控制器會將一組自訂篩選定義為二進位物件，該物件會傳遞至EnableTrace、EnableTraceEx 或 EnableTraceEx2呼叫中的提供者。控制器和提供者必須定義和解譯這些篩選準則，而控制器應該只記錄適用的事件。這需要與控制器和提供者緊密結合，因為無法定義可篩選之物件的二進位物件類型和格式。 TdhEnumerateProviderFilters函式可用來擷取資訊清單中定義的篩選。

如需架構化篩選的詳細資訊，請參閱定義篩選。
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

保留供內部使用。
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

用來擷取特定追蹤會話的取消。傳遞給EnableTraceEx函式的ControlCode參數必須設定為EVENT_CONTROL_CODE_CAPTURE_STATE，而 ProviderId參數必須是SystemTraceControlGuid。 EVENT_FILTER_DESCRIPTOR結構應該指向代表目前 ETW 會話的單一TRACEHANDLE。將會針對該特定會話執行取消。
EVENT_FILTER_TYPE_PID (0x80000004)

處理序識別碼。這是其中一個範圍篩選準則。

根據進程識別碼篩選 ETW 事件會導致事件資料流程 (檔案或即時) ，其中包含來自指定進程中提供者的事件。它只會在提供 PID 的進程中啟用提供者。 PID 清單是呼叫 EnableTraceEx2 時所執行之進程的 PID，而且將會在該特定時間) 提供 PID 的所有進程 (啟用提供者。 PID 清單將不會儲存在會話中。因此，當進程終止並重新出現時，它中的提供者將不會自動啟用至追蹤會話。 PID 型 filter-blob 僅適用于核心模式記錄器會話，因為私人記錄器會話會在使用者模式進程內執行。

可以篩選的進程識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_PID_COUNT為 8。

如果提供進程識別碼篩選準則，則只會在使用者模式進程中啟用提供者。如果相同提供者是由核心模式驅動程式註冊，則不會啟用。

這與全系統私人記錄器 EVENT_TRACE_PROPERTIES_V2 搭配使用。
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

可執行檔名稱。這是其中一個範圍篩選準則。

這與全系統私人記錄器 EVENT_TRACE_PROPERTIES_V2 搭配使用。
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

套件識別碼。這是其中一個範圍篩選準則

這可用來篩選提供者，以從特定 Windows 市集應用程式套件發出的事件。
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

套件相對應用程式識別碼 (PRAID) 。這是其中一個範圍篩選準則

這可用來篩選提供者，以從特定 Windows 市集應用程式套件發出的事件。
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

事件承載 (事件) 的內容。

事件承載篩選的資料大小上限限制為 MAX_EVENT_FILTER_PAYLOAD_SIZEevntprov.h 標頭檔中定義的上限為 4096。
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

事件識別碼。

此功能允許啟用或停用事件清單的篩選。提供的篩選包含 EVENT_FILTER_EVENT_ID 結構，其中包含事件識別碼的陣列，以及指出是否要啟用或停用指定事件的篩選布林值。每個事件寫入呼叫都會快速完成此陣列，以瞭解啟用或停用記錄事件。

套用至 TraceLogging 提供者時，將會忽略此篩選，因為 TraceLogging 事件沒有靜態事件識別碼。

EVENT_FILTER_EVENT_ID結構中允許的事件識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_EVENT_ID_COUNT為 64。
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

TraceLogging 事件名稱。

此功能允許根據其名稱啟用或停用 TraceLogging 事件。提供的篩選包含 EVENT_FILTER_EVENT_NAME 結構，其中包含要篩選的事件名稱陣列、關鍵字位元遮罩和層級，以及指出要啟用或停用描述之事件的布林值。套用至非 TraceLogging 提供者時，會忽略此篩選，因為這些事件在其承載中沒有指定名稱。

注意：可在 Windows 10 1709 版和更新版本上使用。
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

堆疊逐步解說。

當提供者啟用堆疊逐步執行時，就會針對提供者所產生的所有事件擷取堆疊。大部分時候，使用者只對來自特定事件數目的堆疊感興趣。

此功能允許在事件清單上啟用或停用堆疊逐步執行。提供的篩選包含 EVENT_FILTER_EVENT_ID 結構，其中包含事件識別碼的陣列，以及指出是否要啟用或停用指定事件的堆疊擷取的布林值。每個事件寫入呼叫都會快速完成此陣列，以找出是否應該擷取堆疊。

套用至 TraceLogging 提供者時，將會忽略此篩選，因為 TraceLogging 事件沒有靜態事件識別碼。

如果您選擇使用此篩選，當您啟用提供者以從提供者收集任何堆疊時，仍然必須在ENABLE_TRACE_PARAMETERS結構中指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

EVENT_FILTER_EVENT_ID結構中允許的事件識別碼數目上限受限於evntprov.h標頭檔中定義的MAX_EVENT_FILTER_EVENT_ID_COUNT為 64。

注意：可在 Windows 10 1709 版和更新版本上使用。
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

TraceLogging 事件名稱。

此功能允許根據事件名稱篩選 TraceLogging 事件的堆疊集合。提供的篩選包含 EVENT_FILTER_EVENT_NAME 結構，其中包含要篩選的事件名稱、關鍵字位元遮罩和層級陣列，以及指出是否要收集所描述事件的堆疊的布林值。

套用至非 TraceLogging 提供者時，會忽略此篩選，因為這些事件在其承載中沒有指定名稱。

如果您選擇使用此篩選準則，當您讓提供者完全從提供者收集任何堆疊時，仍然必須在ENABLE_TRACE_PARAMETERS結構上指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

注意：可在 Windows 10 1709 版和更新版本上使用。
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

事件層級和關鍵字。

此功能可根據事件的層級和關鍵字，篩選事件的堆疊集合。提供的篩選包含 EVENT_FILTER_LEVEL_KW 結構，其中包含要篩選的關鍵字位元遮罩和層級，以及指出是否要收集所描述事件的堆疊的布林值。

如果您選擇使用此篩選準則，當您讓提供者完全從提供者收集任何堆疊時，仍然必須在ENABLE_TRACE_PARAMETERS結構上指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

注意：可在 Windows 10 1709 版和更新版本上使用。

備註

提供者會決定資料的版面配置及其用途。

在Windows 8.1上，Windows Server 2012 R2 及更新版本、事件承載、範圍和堆疊逐步解說篩選器可供EnableTraceEx2函式和ENABLE_TRACE_PARAMETERS和EVENT_FILTER_DESCRIPTOR結構使用，以篩選記錄器會話中的特定條件。如需事件承載篩選的詳細資訊，請參閱 EnableTraceEx2、 TdhCreatePayloadFilter和 TdhAggregatePayloadFilters 函式和 ENABLE_TRACE_PARAMETERS 和 PAYLOAD_FILTER_PREDICATE 結構。

需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
標頭	evntprov.h