PAYLOAD_FILTER_PREDICATE 結構 (tdh.h)

發行項
03/02/2024

定義事件承載篩選述詞，描述如何篩選追蹤會話中的單一字段。

語法

typedef struct _PAYLOAD_FILTER_PREDICATE {
  LPWSTR FieldName;
  USHORT CompareOp;
  LPWSTR Value;
} PAYLOAD_FILTER_PREDICATE, *PPAYLOAD_FILTER_PREDICATE;

成員

FieldName

要篩選封裝指令清單中的功能變數名稱。

CompareOp

要用於比較的承載運算符。

這個成員可以是 Tdh.h 頭檔中所定義之PAYLOAD_OPERATOR列舉的其中一個值。

值	意義
PAYLOADFIELD_EQ 0	FieldName 參數的值等於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_NE 1	FieldName 參數的值不等於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_LE 2	FieldName 參數的值小於或等於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_GT 3	FieldName 參數的值大於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_LT 4	FieldName 參數的值小於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_GE 5	FieldName 參數的值大於或等於 Value 成員中字串的數值。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_BETWEEN 6	FieldName 參數的值介於 Value 成員中字串中的兩個數值之間。 PAYLOADFIELD_BETWEEN運算符使用關閉的間隔， (LowerBound <= FieldValue <= UpperBound) 。這個運算子用於比較整數，而且需要 Value 成員中的兩個值。這兩個值應該以逗號字元分隔 ('，') 。
PAYLOADFIELD_NOTBETWEEN 7	FieldName 參數的值不在 Value 成員字串中的兩個數值之間。這個運算子用於比較整數，而且需要 Value 成員中的兩個值。這兩個值應該以逗號字元分隔 ('，') 。
PAYLOADFIELD_MODULO 8	FieldName 參數的值是 Value 成員中字串中數值的模數。運算子可用於定期取樣。此運算子用於比較整數，而且在 Value 成員中需要一個值。
PAYLOADFIELD_CONTAINS 20	FieldName 參數的值包含 Value 成員中的子字串值。字串比較不區分大小寫。此運算符用於比較字串，而且在 Value 成員中需要一個值。
PAYLOADFIELD_DOESNTCONTAIN 21	FieldName 參數的值不包含 Value 成員中的子字串。字串比較不區分大小寫。此運算符用於比較字串，而且在 Value 成員中需要一個值。
PAYLOADFIELD_IS 30	FieldName 參數的值與 Value 成員中的字串值相同。字串比較不區分大小寫。此運算符用於比較字串或其他非整數值，而且需要 Value 成員中的一個值。
PAYLOADFIELD_ISNOT 31	FieldName 參數的值與 Value 成員中的字串值不同。字串比較不區分大小寫。此運算符用於比較字串或其他非整數值，而且需要 Value 成員中的一個值。
PAYLOADFIELD_INVALID 32	無效之承載運算子的值。

Value

字串，其中包含要根據 CompareOp 成員比較的一或值。

備註

在 Windows 8.1、Windows Server 2012 R2 和更新版本上，EnableTraceEx2 函式可以使用事件承載篩選，以及ENABLE_TRACE_PARAMETERS和EVENT_FILTER_DESCRIPTOR結構，以篩選記錄器會話中事件的特定內容。

PAYLOAD_FILTER_PREDICATE 結構會與 TdhCreatePayloadFilter 函式搭配使用，以建立單一承載篩選條件，讓單一承載與 EnableTraceEx2 函式搭配使用。您也可以使用 TdhAggregatePayloadFilters 函式與其他單一承載篩選來匯總單一承載篩選。

每個欄位都有提供者指令清單中指定的類型，可用於PAYLOAD_FILTER_PREDICATE結構的 Fieldname 成員，以篩選該欄位。

CompareOp 成員會指定要用於承載篩選的運算符。承載篩選支援篩選字串 (包括 GUID) 和整數， (包括 TDH_INTYPE_FILETIME) 。不支援篩選浮點數、二進位 Blob (包括 TDH_INTYPE_POINTER) ，以及 SID 和 SYSTEMTIME) 的結構化 (數據。

Value 成員包含值或值的字串，以與 Fieldname 成員的值進行比較。 Value 成員會從字串轉換成指令清單中指定的 Fieldname 成員類型。

所有字串比較都區分大小寫。 Value 成員中的字串是 UNICODE，但如果指令清單中指定的類型是 ANSI，則會轉換成 ANSI。

只有在 CompareOp 成員包含承載運算子的PAYLOADFIELD_IS或PAYLOADFIELD_ISNOT時，才能比較包含 GUID 的 Fieldname 成員。代表 Value 成員中 GUID 的字串必須包含大括弧 ({00000000-0000-0000-0000-000000000000}，例如) 。

範例

如需使用 PAYLOAD_FILTER_PREDICATE 結構和 TdhCreatePayloadFilter 函式來建立要用於篩選記錄器會話中特定條件的承載篩選的範例，請參閱 EnableTraceEx2 函式的範例。

規格需求

需求	值
最低支援的用戶端	Windows 8.1 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 R2 [僅限傳統型應用程式]
標頭	tdh.h