Función EventRegister (evntprov.h)

  • Artículo

Registra un proveedor de eventos ETW, creando un identificador que se puede usar para escribir eventos ETW.

Sintaxis

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Parámetros

[in] ProviderId

GUID que identifica de forma única el proveedor, a veces denominado GUID de control. Debe ser un identificador estable para que los controladores de seguimiento puedan usar el GUID para suscribirse a eventos de este proveedor.

[in, optional] EnableCallback

EnableCallback opcional que ETW invocará cuando una sesión de seguimiento habilite o deshabilite este proveedor. Use NULL si no se necesita ninguna devolución de llamada.

[in, optional] CallbackContext

Datos de contexto opcionales que ETW proporcionará al invocar EnableCallback. Use NULL si no se necesita ningún contexto de devolución de llamada.

[out] RegHandle

Recibe el identificador de registro del proveedor de eventos. El identificador se usa en llamadas posteriores a las API del proveedor, como EventWrite, EventProviderEnabled y EventRegister.

Antes de que el proveedor descargue o salga, libere el identificador de registro del proveedor llamando a EventUnregister. Un archivo DLL que se descarga sin liberar todos los identificadores del proveedor que registró puede provocar que el proceso se bloquee.

Valor devuelto

Devuelve ERROR_SUCCESS si se ejecuta correctamente.

El código de error devuelto por EventRegister está pensado principalmente para su uso en escenarios de depuración y diagnóstico. La mayoría del código de producción debe seguir ejecutándose incluso si un proveedor ETW no se pudo registrar, por lo que las compilaciones de versión normalmente deben omitir el código de error devuelto por EventRegister.

Comentarios

EventRegister crea un identificador que puede usar para escribir eventos ETW a través de EventWrite, EventWriteTransfer o EventWriteEx.

Nota:

La mayoría de los proveedores de eventos no llamarán directamente a EventRegister . En su lugar, la mayoría de los proveedores de eventos se implementan mediante un marco ETW que encapsula 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 registro de un proveedor de eventos no debe confundirse con la instalación del manifiesto de un proveedor de eventos.

  • La API EventRegister realiza el registro de un proveedor de eventos para crear un identificador de proveedor. Se trata de una operación de ámbito de proceso (el identificador solo es válido dentro del proceso). El identificador se puede usar para escribir eventos ETW. Todos los eventos escritos mediante el identificador se etiquetarán con el ProviderId que se especificó durante el registro del proveedor. No es necesario instalar un manifiesto para escribir eventos o capturar seguimientos (aunque la instalación del manifiesto puede ser necesaria para descodificar los eventos del proveedor o para que el proveedor funcione con el registro de eventos).
  • La herramienta wevtutil.exe se usa para instalar o desinstalar el manifiesto de un proveedor de eventos. La instalación de un manifiesto de proveedor de eventos significa que la información del manifiesto se registra en el sistema. La información registrada es global del sistema y se conserva hasta que se desinstala el manifiesto. La información grabada incluye los nombres, GUID, canales y rutas dll de recursos de los proveedores definidos en el manifiesto. La información del manifiesto se usa mediante herramientas de descodificación de seguimiento y registro de eventos.

La mayoría de los componentes registrarán su proveedor de eventos en la inicialización de componentes y anularán el registro de su proveedor de eventos en el apagado del componente. Por ejemplo, una aplicación (EXE) puede registrarse durante el inicio de la aplicación y anular el registro durante la salida de la aplicación. Una biblioteca dinámica (DLL) puede registrarse durante DllMain la asociación de procesos y anular el registro durante DllMain la desasociación del proceso.

Dado que el seguimiento de eventos es un problema de depuración o diagnóstico y no suele ser una funcionalidad crítica para la aplicación, la mayoría de las aplicaciones comerciales deben omitir silenciosamente los errores devueltos por EventRegister. En caso de error, EventRegister establecerá el parámetro RegHandle en cero para que los usos posteriores de RegHandle (es decir, en llamadas a EventWrite y EventUnregister) no tendrán ningún efecto.

Cada proceso puede registrar hasta 1024 proveedores. Sin embargo, debe limitar el número de proveedores que registra el componente en uno o dos. Este límite incluye proveedores registrados mediante esta función y proveedores registrados mediante RegisterTraceGuids.

Antes de Windows Vista: No hay ningún límite específico para el número de proveedores que un proceso puede registrar.

Requisitos

   
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado evntprov.h
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

EnableCallback

EventWrite

EventUnregister