Funzione TdhCreatePayloadFilter (tdh.h)

La funzione TdhCreatePayloadFilter crea un singolo filtro per un singolo payload da usare con la funzione EnableTraceEx2 .

Sintassi

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

Parametri

[in] ProviderGuid

GUID che identifica il provider manifesto del parametro EventDescriptor .

[in] EventDescriptor

Puntatore al descrittore dell'evento il cui payload verrà filtrato.

[in] EventMatchANY

Valore booleano che indica come vengono gestiti gli eventi quando vengono specificate più condizioni.

Quando questo parametro è TRUE, un evento verrà scritto in una sessione se una delle condizioni specificate nel filtro è TRUE.

Quando questo parametro è FALSE, un evento verrà scritto in una sessione solo se tutte le condizioni specificate specificate nel filtro sono TRUE.

[in] PayloadPredicateCount

Numero di condizioni specificate nel filtro. Questo valore deve essere minore o uguale alla costante ETW_MAX_PAYLOAD_PREDICATES definita nel file di intestazione Tdhh.h .

[in] PayloadPredicates

Puntatore a una matrice di strutture PAYLOAD_FILTER_PREDICATE che contengono le condizioni di elenco specificate dal filtro.

[out] PayloadFilter

In caso di esito positivo, questo parametro restituisce un puntatore a un singolo filtro payload che viene ridimensionato correttamente e compilato per le condizioni specificate.

Al termine dell'uso del filtro payload restituito con la funzione EnableTraceEx2 , la funzione TdhDeletePayloadFilter deve essere chiamata per liberare la memoria allocata.

Valore restituito

Restituisce ERROR_SUCCESS se riuscito. In caso contrario, questa funzione restituisce uno dei codici restituiti seguenti oltre ad altri.

Commenti

In Windows 8.1, Windows Server 2012 R2 e versioni successive, i filtri del payload degli eventi possono essere usati dalla funzione EnableTraceEx2 per filtrare il contenuto specifico dell'evento in una sessione del logger.

La funzione TdhCreatePayloadFilter viene usata per creare un singolo filtro payload per un singolo payload da usare con la funzione EnableTraceEx2 . TdhCreatePayloadFilter alloca e riempie una struttura di dati opaca per un singolo filtro payload. Quando il filtro del payload non è più necessario, la funzione TdhDeletePayloadFilter viene usata per liberare memoria allocata per un filtro payload.

Per un singolo provider, più eventi possono avere filtri payload distinti. Possono essere presenti anche più filtri per lo stesso evento, con un payload passato alla sessione se uno o tutti i filtri dell'evento lo passano.

La funzione EnableTraceEx2 accetta una matrice di strutture EVENT_FILTER_DESCRIPTOR nelle struttureENABLE_TRACE_PARAMETERS passate nel parametro EnableParameters. È possibile inserire una sola voce nella matrice per ogni tipo di filtro eventi. La funzione TdhAggregatePayloadFilters può essere usata per aggregare un elenco di filtri payload per un singolo provider creato usando TdhCreatePayloadFilter in una singola struttura di dati e restituire un EVENT_FILTER_DESCRIPTOR da usare con la funzione EnableTraceEx2 .

Esempio

Per un esempio che usa la funzione TdhCreatePayloadFilter per creare filtri payload da usare in condizioni specifiche in una sessione di logger, vedere l'esempio per la funzione EnableTraceEx2 .

Requisiti

Vedi anche

ENABLE_TRACE_PARAMETERS

EVENT_DESCRIPTOR

EVENT_FILTER_DESCRIPTOR

EnableTraceEx2

PAYLOAD_FILTER_PREDICATE

TdhAggregatePayloadFilters

TdhCleanupPayloadEventFilterDescriptor

TdhDeletePayloadFilter