PAYLOAD_FILTER_PREDICATE structure (tdh.h)

Defines an event payload filter predicate that describes how to filter on a single field in a trace session.

Syntax

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

Members

FieldName

The name of the field to filter in package manifest.

CompareOp

The payload operator to use for the comparison.

This member can be one of the values for the PAYLOAD_OPERATOR enumeration defined in the Tdh.h header file.

Value Meaning
PAYLOADFIELD_EQ
0
The value of the FieldName parameter is equal to the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_NE
1
The value of the FieldName parameter is not equal to the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_LE
2
The value of the FieldName parameter is less than or equal to the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_GT
3
The value of the FieldName parameter is greater than the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_LT
4
The value of the FieldName parameter is less than the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_GE
5
The value of the FieldName parameter is greater than or equal to the numeric value of the string in the Value member.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_BETWEEN
6
The value of the FieldName parameter is between the two numeric values in the string in the Value member. The PAYLOADFIELD_BETWEEN operator uses a closed interval (LowerBound <= FieldValue <= UpperBound).

This operator is for comparing integers and requires two values in the Value member. The two values should be separated by a comma character (',').

PAYLOADFIELD_NOTBETWEEN
7
The value of the FieldName parameter is not between the two numeric values in the string in the Value member.

This operator is for comparing integers and requires two values in the Value member. The two values should be separated by a comma character (',').

PAYLOADFIELD_MODULO
8
The value of the FieldName parameter is the modulo of the numeric value in the string in the Value member. The operator can be used for periodic sampling.

This operator is for comparing integers and requires one value in the Value member.

PAYLOADFIELD_CONTAINS
20
The value of the FieldName parameter contains the substring value in the Value member. String comparisons are case insensitive.

This operator is for comparing strings and requires one value in the Value member.

PAYLOADFIELD_DOESNTCONTAIN
21
The value of the FieldName parameter does not contain the substring in the Value member. String comparisons are case insensitive.

This operator is for comparing strings and requires one value in the Value member.

PAYLOADFIELD_IS
30
The value of the FieldName parameter is identical to the value of the string in the Value member. String comparisons are case insensitive.

This operator is for comparing strings or other non-integer values and requires one value in the Value member.

PAYLOADFIELD_ISNOT
31
The value of the FieldName parameter is not identical to the value of the string in the Value member. String comparisons are case insensitive.

This operator is for comparing strings or other non-integer values and requires one value in the Value member.

PAYLOADFIELD_INVALID
32
A value of the payload operator that is not valid.

Value

The string that contains one or values to compare depending on the CompareOp member.

Remarks

On Windows 8.1,Windows Server 2012 R2, and later, event payload filters can be used by the EnableTraceEx2 function and the ENABLE_TRACE_PARAMETERS and EVENT_FILTER_DESCRIPTOR structures to filter on the specific content of the event in a logger session.

The PAYLOAD_FILTER_PREDICATE structure is used with the TdhCreatePayloadFilter function to create a single payload filter for a single payload to be used with the EnableTraceEx2 function. A single payload filter can also be aggregated with other single payload filters using the TdhAggregatePayloadFilters function.

Each field has a type specified in the provider manifest that can be used in the Fieldname member of the PAYLOAD_FILTER_PREDICATE structure to filter on that field.

The CompareOp member specifies that operator to use for payload filtering. Payload filtering supports filtering on a string (including a GUID) and integers (including TDH_INTYPE_FILETIME). Filtering on floating-point numbers, a binary blob (including TDH_INTYPE_POINTER), and structured data (SID and SYSTEMTIME) are not supported.

The Value member contains a string of the value or values to compare with the value of the Fieldname member. The Value member is converted from a string to the type of the Fieldname member as specified in the manifest.

All string comparisons are case-insensitive. The string in the Value member is UNICODE, but it will be converted to ANSI if the type specified in the manifest is ANSI.

A Fieldname member that contains a GUID can only be compared when the CompareOp member contains either the PAYLOADFIELD_IS or PAYLOADFIELD_ISNOT for the payload operator. The string that represents a GUID in the Value member must contain the curly brackets ({00000000-0000-0000-0000-000000000000}, for example).

Examples

For an example that uses the PAYLOAD_FILTER_PREDICATE structure and the TdhCreatePayloadFilter function to create payload filters to use in filtering on specific conditions in a logger session, see the example for the EnableTraceEx2 function.

Requirements

Requirement Value
Minimum supported client Windows 8.1 [desktop apps only]
Minimum supported server Windows Server 2012 R2 [desktop apps only]
Header tdh.h

See also

ENABLE_TRACE_PARAMETERS

EVENT_DESCRIPTOR

EVENT_FILTER_DESCRIPTOR

EnableTraceEx2

TdhAggregatePayloadFilters

TdhCreatePayloadFilter