Función de devolución de llamada PENABLECALLBACK (evntprov.h)

Los proveedores de eventos ETW definen opcionalmente una función EnableCallback para recibir notificaciones de cambio de configuración. El tipo PENABLECALLBACK define un puntero a esta función de devolución de llamada. EnableCallback es un marcador de posición para el nombre de función definido por la aplicación.

Sintaxis

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Parámetros

[in] SourceId

GUID especificado por el autor de la llamada que habilita o deshabilita el proveedor.

El valor procede del parámetro SourceId de EnableTraceEx o del campo SourceId del ENABLE_TRACE_PARAMETERS que se pasa a EnableTraceEx2.

Nota

SourceId es el valor de la sesión especificada en la llamada a la API EnableTraceEx o EnableTraceEx2. Puede que sea o no el mismo que el GUID de la sesión.

SourceId se establecerá en GUID_NULL en varios escenarios en los que la notificación no tiene un identificador de origen. Por ejemplo, esto puede ocurrir cuando una sesión de seguimiento habilitó el proveedor antes de iniciarse el proveedor, cuando el proveedor se detiene o cuando un controlador de seguimiento llama a una API EnableTrace sin especificar un SourceId.

[in] IsEnabled

Indica el controlCode correspondiente a esta notificación. Puede ser uno de los siguientes valores:

Valor	Significado
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	No hay sesiones habilitadas para el proveedor.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	Una o varias sesiones han habilitado el proveedor.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	Una sesión solicita que el proveedor registre su información de estado. Normalmente, el proveedor responderá escribiendo eventos que contengan el estado del proveedor.

Nota:

Es posible que el valor de IsEnabled no sea el mismo que controlCode pasado a la API EnableTrace que desencadenó este evento. Por ejemplo, si dos sesiones han habilitado este proveedor y una sesión deshabilita este proveedor llamando a EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), el proveedor recibirá una notificación con IsEnabled establecida EVENT_CONTROL_CODE_ENABLE_PROVIDER en porque el proveedor todavía está habilitado por la otra sesión.

Después de recibir una notificación de DISABLE_PROVIDER , un proveedor puede optimizar su rendimiento deshabilitando todos los eventos. Después de recibir una notificación de ENABLE_PROVIDER , un proveedor debe habilitar la escritura de eventos. También puede optimizar su rendimiento mediante la grabación de los valores de los filtros Level, MatchAnyKeyword y MatchAllKeyword y, a continuación, solo escribiendo los eventos que pasan los filtros (como se describe en los comentarios). Después de recibir una notificación de CAPTURE_STATE , un proveedor puede realizar cualquier acción que parezca adecuada, normalmente escribiendo eventos que describen la configuración o el estado del componente.

Un proveedor debe omitir las notificaciones con valores IsEnabled que no reconoce ni admite.

[in] Level

Valor que especifica el nivel de detalle de los eventos que el proveedor debe escribir. Cuando se invoca con el código de control EVENT_CONTROL_CODE_ENABLE_PROVIDER, el proveedor debe registrar el valor Level y, posteriormente, omitir eventos en los que el nivel de detalle del evento es mayor que el nivel de detalle del evento, es decir, un evento solo debe escribirse si

eventDescriptor.Level <= recorded.Level

El nivel de la notificación es el máximo de los niveles especificados por los controladores de seguimiento en llamadas a EnableTrace, EnableTraceEx o EnableTraceEx2 mediante el GUID de este proveedor de eventos. En otras palabras, si varias sesiones están grabando eventos de este proveedor de eventos en distintos niveles de detalle, el parámetro Level de la notificación EnableCallback se establecerá en el más alto (más detallado) de los niveles.

[in] MatchAnyKeyword

Valor de máscara de bits que especifica categorías de eventos que el proveedor debe escribir. Cuando se invoca con el código de control EVENT_CONTROL_CODE_ENABLE_PROVIDER, el proveedor debe registrar el valor MatchAnyKeyword y, posteriormente, omitir eventos en los que la palabra clave del evento es distinto de cero y no tiene ninguno de los bits del matchAnyKeyword grabado, es decir, un evento solo debe escribirse si la palabra clave del evento no es cero y no tiene ninguno de los bits del matchAnyKeyword grabado, es decir, un evento solo debe escribirse si

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

MatchAnyKeyword de la notificación es la unión (OR) de las palabras clave match-any (habilitar marcas) especificadas por los controladores de seguimiento en llamadas a EnableTrace, EnableTraceEx y EnableTraceEx2 para el GUID de este proveedor de eventos. En otras palabras, si varias sesiones están grabando eventos de este proveedor de eventos con distintos filtros de palabra clave match-any, el parámetro MatchAnyKeyword para la notificación EnableCallback se establecerá en el bit aOR bit- de los filtros de palabra clave match-any de las sesiones.

MatchAllKeyword

Valor de máscara de bits que especifica categorías de eventos que el proveedor debe escribir. Cuando se notifica con el código de control EVENT_CONTROL_CODE_ENABLE_PROVIDER, el proveedor debe registrar el valor MatchAllKeyword y, posteriormente, omitir eventos en los que la palabra clave del evento es distinto de cero y no tiene todos los bits del matchAllKeyword grabado, es decir, un evento solo debe escribirse si la palabra clave del evento no es cero y no tiene todos los bits del matchAllKeyword grabado, es decir, un evento solo debe escribirse si

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

MatchAllKeyword de la notificación es la disjunción (AND) de las palabras clave match-all especificadas por los controladores de seguimiento en llamadas a EnableTraceEx y EnableTraceEx2 para el GUID de este proveedor de eventos. En otras palabras, si varias sesiones están grabando eventos de este proveedor de eventos con diferentes filtros de palabra clave match-all, el parámetro MatchAllKeyword para la notificación EnableCallback se establecerá en el bit a bit-AND de los filtros de palabra clave match-all de las sesiones.

[in, optional] FilterData

Puntero a un EVENT_FILTER_DESCRIPTOR con datos de filtro para el proveedor de eventos.

Cada sesión solo puede especificar un filtro. El descriptor de filtro de la notificación de devolución de llamada contendrá un filtro de cada sesión que especificó datos de filtro al habilitar el proveedor.

Los datos de filtro solo son válidos dentro de la devolución de llamada. Los proveedores deben realizar una copia local de los datos si los datos serán necesarios después de que se devuelva la devolución de llamada.

[in, optional] CallbackContext

Contexto de la devolución de llamada. Este es el valor del parámetro CallbackContext que se usó cuando el proveedor de eventos llamó a EventRegister.

Valor devuelto

None

Observaciones

Los proveedores de eventos ETW que necesitan notificaciones de cambio de configuración deben proporcionar un puntero a su implementación EnableCallback cuando se registran a través de EventRegister. ETW invocará la función EnableCallback del proveedor cuando se realice un cambio en la configuración de una sesión de seguimiento que implique al proveedor. Por ejemplo, cuando un controlador de sesión de seguimiento configura un seguimiento a través de EnableTraceEx2 o detiene un seguimiento a través de ControlTrace, ETW llamará a la función EnableCallback del proveedor con la configuración actualizada resultante.

Nota

La mayoría de los proveedores de eventos no implementarán EnableCallback directamente. En su lugar, la mayoría de los proveedores de eventos se implementan mediante un marco ETW que proporciona su propia implementación enableCallback y ajusta las llamadas a EventRegister, EventWrite y EventUnregister. Por ejemplo, puede escribir un manifiesto de evento y, a continuación, usar el compilador de mensajes para generar código de C/C++ para los eventos, o puede usar TraceLogging para evitar la necesidad de un manifiesto. El marco ETW suele implementar una función EnableCallback que registra los valores , MatchAnyKeywordy MatchAllKeyword de la notificaciónLevel, y el marco usa automáticamente los valores registrados para filtrar eventos. El marco ETW normalmente admite la invocación de una devolución de llamada proporcionada por el usuario si el usuario requiere un control de notificaciones personalizado. Por ejemplo, TraceLoggingProvider.h permite especificar una devolución de llamada de notificación a través de TraceLoggingRegisterEx.

Importante

La función EnableCallback del proveedor debe ser lo más sencilla posible. Debe registrar la información necesaria y volver rápidamente. Una función de devolución de llamada de larga duración puede provocar retrasos en las API de control de sesión de ETW, como EnableTraceEx2 o ControlTrace. La función de devolución de llamada no debe hacer nada que requiera el bloqueo del cargador del proceso, es decir, no debe llamar directa o indirectamente a LoadLibrary o FreeLibrary. La función de devolución de llamada no debe bloquearse en bloqueos. La función de devolución de llamada puede provocar un interbloqueo si se bloquea o si invoca cualquier API de control de sesión ETW, como StartTrace, ControlTrace o EnableTrace.

La devolución de llamada de notificación permite que el proveedor de eventos se ejecute de forma más eficaz porque el proveedor puede realizar su propio seguimiento del nivel, las palabras clave y otros filtros. Al realizar el seguimiento de los filtros, el proveedor puede omitir eficazmente los eventos que no están habilitados (es decir, el proveedor no necesita preparar los datos del evento ni llamar a EventWrite para los eventos que no son necesarios para ninguna sesión de seguimiento).

Tenga en cuenta que el seguimiento de filtros no es necesario para el funcionamiento correcto de un proveedor: ETW proporciona funciones EventEnabled y EventProviderEnabled que un proveedor puede usar y las API eventW de ETW omitirán silenciosamente los eventos deshabilitados. Sin embargo, el seguimiento de filtros implementado por el proveedor puede ser más eficaz que las llamadas a EventEnabled o EventProviderEnabled.

La devolución de llamada de notificación también permite al proveedor controlar las solicitudes de "estado de captura" de las sesiones de seguimiento. Normalmente, las solicitudes de estado de captura se envían mediante una sesión de seguimiento cuando comienza a grabar eventos de un proveedor. Si un proveedor admite el estado de captura, puede responder a la solicitud de estado de captura registrando información de estado, por ejemplo, información de configuración o estadísticas de resumen con respecto a la operación del componente antes de la solicitud.

El valor Level que ETW pasa a la devolución de llamada es el valor de nivel más alto (más detallado) especificado para este proveedor de eventos mediante cualquier sesión de seguimiento en ejecución. Por ejemplo, si la sesión A ha habilitado este proveedor para eventos de advertencia (nivel 3) y, a continuación, la sesión B habilita el proveedor para eventos críticos (nivel 1), el valor nivel de la devolución de llamada será 3, no 1.

Del mismo modo, los valores MatchAnyKeyword y MatchAllKeyword son valores compuestos calculados a partir de la configuración de todas las sesiones que han habilitado el proveedor de eventos. MatchAnyKeyword es el OR de la configuración EnableFlags/MatchAnyKeyword de las sesiones. MatchAllKeyword es el AND de la configuración MatchAllKeyword de las sesiones.

Si la función EnableCallback del proveedor ha capturado el estado Enabled, Level, MatchAnyKeyword y MatchAllKeyword del proveedor, el proveedor puede determinar si un evento debe escribirse con una función como la siguiente:

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Requisitos

Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	evntprov.h

Consulte también

EventRegister

EnableTrace

EnableTraceEx2