Función TdhCreatePayloadFilter (tdh.h)
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 |
|---|---|
|
No se encontraron los metadatos del proveedor. |
|
Uno o varios de los parámetros no son válidos. |
|
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. |
|
No se puede asignar memoria para crear el filtro de carga. |
|
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 |