Función TdhCreatePayloadFilter (tdh.h)

Artículo
03/08/2023

La función TdhCreatePayloadFilter crea un único filtro para una sola carga que se usará con la función EnableTraceEx2 .

Sintaxis

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

Parámetros

[in] ProviderGuid

GUID que identifica el proveedor de manifiestos del parámetro EventDescriptor .

[in] EventDescriptor

Puntero al descriptor de eventos cuya carga se filtrará.

[in] EventMatchANY

Valor booleano que indica cómo se controlan los eventos cuando se especifican varias condiciones.

Cuando este parámetro es TRUE, se escribirá un evento en una sesión si alguna de las condiciones especificadas en el filtro es TRUE.

Cuando este parámetro es FALSE, un evento se escribirá en una sesión solo si todas las condiciones especificadas en el filtro son TRUE.

[in] PayloadPredicateCount

Número de condiciones especificadas en el filtro. Este valor debe ser menor o igual que la constante ETW_MAX_PAYLOAD_PREDICATES definida en el archivo de encabezado Tdh.h .

[in] PayloadPredicates

Puntero a una matriz de estructuras de PAYLOAD_FILTER_PREDICATE que contienen las condiciones de lista que especifica el filtro.

[out] PayloadFilter

Si se ejecuta correctamente, este parámetro devuelve un puntero a un único filtro de carga que tiene el tamaño adecuado y se compila para las condiciones especificadas.

Cuando el autor de la llamada termine de usar el filtro de carga devuelto con la función EnableTraceEx2 , se debe llamar a la función TdhDeletePayloadFilter para liberar la memoria asignada.

Valor devuelto

Devuelve ERROR_SUCCESS si se ejecuta correctamente. De lo contrario, esta función devuelve uno de los siguientes códigos de retorno además de otros.

Código devuelto	Descripción
ERROR_FILE_NOT_FOUND	No se encontraron los metadatos del proveedor.
ERROR_INVALID_PARAMETER	Uno o varios de los parámetros no son válidos.
ERROR_INSUFFICIENT_BUFFER	El filtro de carga resultante no cabría dentro del límite de MAX_EVENT_FILTER_PAYLOAD_SIZE impuesto por la función EnableTraceEx2 en las estructuras de EVENT_FILTER_DESCRIPTOR de una carga.
ERROR_NOT_ENOUGH_MEMORY	No se puede asignar memoria para crear el filtro de carga.
ERROR_NOT_FOUND	No se encontró la información de esquema para el GUID del proveedor proporcionado.

Comentarios

En Windows 8.1, Windows Server 2012 R2 y versiones posteriores, la función EnableTraceEx2 puede usar filtros de carga de eventos para filtrar por el contenido específico del evento en una sesión del registrador.

La función TdhCreatePayloadFilter se usa para crear un único filtro de carga útil para una sola carga que se usará con la función EnableTraceEx2 . TdhCreatePayloadFilter asigna y rellena una estructura de datos opaca para un único filtro de carga. Cuando el filtro de carga ya no es necesario, la función TdhDeletePayloadFilter se usa para liberar memoria asignada para un filtro de carga.

Para un único proveedor, varios eventos pueden tener filtros de carga distintos. También puede haber varios filtros para el mismo evento, con una carga que se pasa a la sesión si alguno o todos los filtros del evento lo pasan.

La función EnableTraceEx2 toma una matriz de estructuras de EVENT_FILTER_DESCRIPTOR en las estructuras de ENABLE_TRACE_PARAMETERS pasadas en el parámetro EnableParameters . Solo puede haber una entrada en la matriz para cada tipo de filtro de evento. La función TdhAggregatePayloadFilters se puede usar para agregar una lista de filtros de carga para un único proveedor creado mediante TdhCreatePayloadFilter en una única estructura de datos y devolver un EVENT_FILTER_DESCRIPTOR para su uso con la función EnableTraceEx2 .

Ejemplos

Para obtener un ejemplo que usa la función TdhCreatePayloadFilter para crear filtros de carga para usarlos en el filtrado de condiciones específicas en una sesión de registrador, vea el ejemplo de la función EnableTraceEx2 .

Requisitos


Cliente mínimo compatible	Windows 8.1 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	tdh.h
Library	Tdh.lib
Archivo DLL	Tdh.dll