Función EtwRegister (wdm.h)

La función EtwRegister registra el proveedor de eventos y se debe llamar para que un proveedor pueda iniciar el seguimiento. La función EtwRegister es el homólogo del modo kernel de la función EventRegister en modo de usuario. La función también puede proporcionar un puntero a una función de devolución de llamada opcional que se puede usar para proporcionar funcionalidades adicionales de filtrado de eventos.

Sintaxis

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

Parámetros

[in] ProviderId

Puntero al GUID del proveedor de eventos.

[in, optional] EnableCallback

Puntero a una función de devolución de llamada opcional. La función de devolución de llamada proporciona funcionalidades adicionales de filtrado de eventos. La función de devolución de llamada está definida por el usuario.

[in, optional] CallbackContext

La función pasa el contexto de devolución de llamada opcional cuando se realiza una devolución de llamada. Puede especificar el contexto opcional al registrar un proveedor. El parámetro CallbackContext admite los escenarios en los que varios proveedores comparten una devolución de llamada, como en una clase de C++. CallbackContext proporciona una manera de distinguir las instancias del proveedor de destino para la devolución de llamada de habilitación.

[out] RegHandle

Puntero a una variable que recibe el identificador de registro del proveedor si la llamada de función se realiza correctamente.

Valor devuelto

La función EtwRegister devuelve un código de estado de la lista siguiente:

Código devuelto	Descripción
STATUS_SUCCESS	Indica que el proveedor de eventos se registró correctamente con ETW.
STATUS_INVALID_PARAMETER	Indica que el parámetro no era válido.
STATUS_Xxx	Indica que se produjo un error en la solicitud por el motivo especificado por el valor NTSTATUS. Consulte Ntstatus.h para obtener información detallada sobre el código de retorno de estado real.

Comentarios

Para que un controlador en modo kernel pueda realizar un seguimiento de eventos, el controlador debe registrarse como proveedor de eventos mediante la función EtwRegister . Cuando un controlador en modo kernel llama a EtwRegister, la función devuelve un identificador de registro. Este identificador de registro se puede usar para probar si una palabra clave o nivel está habilitada para un proveedor específico y para llamar a las funciones de seguimiento y registro de eventos. Una vez completado el seguimiento, un controlador debe llamar a la función EtwUnregister para anular el registro del proveedor. Para cada llamada a EtwRegister , debe haber una llamada correspondiente a EtwUnregister. Si no se anula el registro del proveedor de eventos, se pueden producir errores cuando se descarga el proceso porque las funciones de devolución de llamada asociadas al proceso ya no son válidas. No se debe realizar ninguna llamada de seguimiento que se encuentre fuera del código enlazado por las funciones EtwRegister y EtwUnregister . Para obtener el mejor rendimiento, puede llamar a la función EtwRegister en la rutina DriverEntry y la función EtwUnregister en la rutina DriverUnload .

Los autores de llamadas de EtwRegister deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Consulte también

EtwUnregister