Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

TdhAggregatePayloadFilters function

The TdhAggregatePayloadFilters function aggregates multiple payload filters for a single provider into a single data structure for use with the EnableTraceEx2 function.

Syntax


ULONG TDHAPI TdhAggregatePayloadFilters(
           ULONG                    PayloadFilterCount,
           PVOID                    PayloadFilterPtrs,
  _In_opt_ PBOOLEAN                 EventMatchAllFlags,
  _Out_    PEVENT_FILTER_DESCRIPTOR EventFilterDescriptor
);

Parameters

PayloadFilterCount

The count of payload filters.

PayloadFilterPtrs

An array of event payload single filters, each created by a call to the TdhCreatePayloadFilter function.

EventMatchAllFlags [in, optional]

An array of Boolean values that correspond to each payload filter passed in the PayloadFilterPtrs parameter and indicates how events are handled when multiple conditions are specified.. This parameter only affects situations where multiple payload filters are being specified for the same event.

When a Boolean value is TRUE, an event will be written to a session if any of the specified conditions specified in the filter are TRUE. If this flag is set to TRUE on one or more filters for the same event Id or event version, then the event is only written if all the flagged filters for the event are satisfied.

When a Boolean value is FALSE, an event will be written to a session only if all of the specified conditions specified in the filter are TRUE. If this flag is set to FALSE on one or more filters for the same event Id or event version, then the event is written if any of the non-flagged filters are satisfied.

EventFilterDescriptor [out]

A pointer to an EVENT_FILTER_DESCRIPTOR structure to be used with the EnableTraceEx2 function. The EVENT_FILTER_DESCRIPTOR structure will contain a pointer to the aggregated payload filters, which have been allocated by this function.

When the caller is finished using this EVENT_FILTER_DESCRIPTOR structure with the EnableTraceEx2 function, the TdhCleanupPayloadEventFilterDescriptor 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 codeDescription
ERROR_INVALID_PARAMETER

One or more of the parameters is not valid.

ERROR_NOT_ENOUGH_MEMORY

Unable to allocate memory to create the aggregated payload filter.

 

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 the event in a logger session.

The TdhAggregatePayloadFilters function aggregates payload filters for a single provider into a single data structure for use with the EnableTraceEx2 function. The TdhAggregatePayloadFilters allocates and fills in an opaque data structure for an aggregated payload filter. When the aggregated payload filter is no longer needed, the TdhCleanupPayloadEventFilterDescriptor function is used to free memory allocated for the aggregated payload filter in the EVENT_FILTER_DESCRIPTOR structure returned.

Examples

For an example that uses the TdhAggregatePayloadFilters function to aggregate payload filters to use in filtering on specific conditions in a logger session, see the example for the EnableTraceEx2 function.

Requirements

Minimum supported client

Windows 8.1 [desktop apps only]

Minimum supported server

Windows Server 2012 R2 [desktop apps only]

Header

Tdh.h

Library

Tdh.lib

DLL

Tdh.dll

See also

EnableTraceEx2
ENABLE_TRACE_PARAMETERS
EVENT_FILTER_DESCRIPTOR
TdhCleanupPayloadEventFilterDescriptor
TdhCreatePayloadFilter
TdhDeletePayloadFilter

 

 

Community Additions

ADD
Show:
© 2015 Microsoft