TdhCreatePayloadFilter function (tdh.h)

Article
10/13/2021

The TdhCreatePayloadFilter function creates a single filter for a single payload to be used with the EnableTraceEx2 function.

Syntax

TDHSTATUS TdhCreatePayloadFilter(
  [in]  LPCGUID                   ProviderGuid,
  [in]  PCEVENT_DESCRIPTOR        EventDescriptor,
  [in]  BOOLEAN                   EventMatchANY,
  [in]  ULONG                     PayloadPredicateCount,
  [in]  PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
  [out] PVOID                     *PayloadFilter
);

Parameters

[in] ProviderGuid

A GUID that identifies the manifest provider of the EventDescriptor parameter.

[in] EventDescriptor

A pointer to the event descriptor whose payload will be filtered.

[in] EventMatchANY

A Boolean value that indicates how events are handled when multiple conditions are specified.

When this parameter is TRUE, an event will be written to a session if any of the specified conditions specified in the filter are TRUE.

When this parameter is FALSE, an event will be written to a session only if all of the specified conditions specified in the filter are TRUE.

[in] PayloadPredicateCount

The number of conditions specified in the filter. This value must be less than or equal to the ETW_MAX_PAYLOAD_PREDICATES constant defined in the Tdh.h header file.

[in] PayloadPredicates

A pointer to an array of PAYLOAD_FILTER_PREDICATE structures that contain the list conditions that the filter specifies.

[out] PayloadFilter

On success, this parameter returns a pointer to a single payload filter that is properly sized and built for the specified conditions.

When the caller is finished using the returned payload filter with the EnableTraceEx2 function, the TdhDeletePayloadFilter function should be called to free the allocated memory.

Return value

Returns ERROR_SUCCESS if successful. Otherwise, this function returns one of the following return codes in addition to others.

Return code	Description
ERROR_FILE_NOT_FOUND	The metadata for the provider was not found.
ERROR_INVALID_PARAMETER	One or more of the parameters is not valid.
ERROR_INSUFFICIENT_BUFFER	The resulting payload filter would not fit within the MAX_EVENT_FILTER_PAYLOAD_SIZE limit imposed by the EnableTraceEx2 function on the EVENT_FILTER_DESCRIPTOR structures in a payload.
ERROR_NOT_ENOUGH_MEMORY	Unable to allocate memory to create the payload filter.
ERROR_NOT_FOUND	The schema information for supplied provider GUID was not found.

Remarks

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

The TdhCreatePayloadFilter function is used to create a single payload filter for a single payload to be used with the EnableTraceEx2 function. The TdhCreatePayloadFilter allocates and fills in an opaque data structure for a single payload filter. When the payload filter is no longer needed, the TdhDeletePayloadFilter function is used to free memory allocated for a payload filter.

For a single provider, multiple events can have distinct payload filters. There can also be multiple filters for the same event, with a payload being passed to the session if any or all of the event's filters pass it.

The EnableTraceEx2 function takes an array of EVENT_FILTER_DESCRIPTOR structures in the ENABLE_TRACE_PARAMETERS structures passed in the EnableParameters parameter. There can only be one entry in the array for each event filter type. The TdhAggregatePayloadFilters function can be used to aggregate a list of payload filters for a single provider created using the TdhCreatePayloadFilter into a single data structure and return an EVENT_FILTER_DESCRIPTOR for use with the EnableTraceEx2 function.

Examples

For an example that uses 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]
Target Platform	Windows
Header	tdh.h
Library	Tdh.lib
DLL	Tdh.dll