Funzione TdhCreatePayloadFilter (tdh.h)

Articolo
03/08/2023

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.

Codice restituito	Descrizione
ERROR_FILE_NOT_FOUND	I metadati per il provider non sono stati trovati.
ERROR_INVALID_PARAMETER	Uno o più parametri non sono validi.
ERROR_INSUFFICIENT_BUFFER	Il filtro payload risultante non rientra nel limite MAX_EVENT_FILTER_PAYLOAD_SIZE imposto dalla funzione EnableTraceEx2 nelle strutture EVENT_FILTER_DESCRIPTOR in un payload.
ERROR_NOT_ENOUGH_MEMORY	Impossibile allocare memoria per creare il filtro del payload.
ERROR_NOT_FOUND	Non sono state trovate le informazioni sullo schema per il GUID del provider fornito.

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 strutture ENABLE_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


Client minimo supportato	Windows 8.1 [solo app desktop]
Server minimo supportato	Windows Server 2012 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	tdh.h
Libreria	Tdh.lib
DLL	Tdh.dll