Función TraceLoggingRegister (traceloggingprovider.h)
Registra un proveedor traceLogging para que se pueda usar para registrar eventos. El registro es válido hasta que se anula el registro del proveedor o se cierra el proceso.
Sintaxis
TLG_STATUS TraceLoggingRegister(
TraceLoggingHProvider hProvider
);
Parámetros
hProvider
Identificador del proveedor traceLogging que se va a registrar. El identificador aún no debe estar registrado.
Valor devuelto
Si llama a esta función desde código en modo de usuario, la función devuelve un HRESULT. Use la SUCCEEDED() macro para determinar si la función se realiza correctamente.
Si llama a esta función desde código en modo kernel, la función devuelve .NTSTATUS Use la NT_SUCCESS() macro para determinar si la función se realiza correctamente.
Nota
El código de error devuelto por TraceLoggingRegister 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 TraceLoggingRegister.
Comentarios
Cuando se inicia la ejecución de un componente, cualquier identificador del proveedor de seguimiento del componente estará en un estado no registrado y los intentos de usar el identificador del proveedor para generar eventos se omitirán de forma silenciosa. Para que el proveedor pueda escribir cualquier evento, debe registrar el proveedor mediante TraceLoggingRegister. Normalmente, lo hará durante el inicio del componente, por ejemplo, en main, wmain, WinMainDllMain(DLL_PROCESS_ATTACH)o DriverEntry. En el apagado del componente, anule el registro del proveedor mediante una llamada a TraceLoggingUnregister.
No llame a TraceLoggingRegister en un identificador de proveedor que ya esté registrado. Puede anular el registro de un identificador y, a continuación, registrarlo de nuevo si es necesario, aunque registrar y anular el registro repetidamente el identificador puede provocar problemas de rendimiento y debe evitarse (es decir, no registrar, escribir algunos eventos y, a continuación, anular el registro; en su lugar, registrar una vez en el inicio del componente y anular el registro en el apagado del componente).
TraceLoggingRegister no es seguro para subprocesos con respecto a otras llamadas a TraceLoggingRegister o TraceLoggingUnregister en el mismo identificador. No llame a TraceLoggingRegister si es posible que otro subproceso llame a TraceLoggingRegister o TraceLoggingUnregister en el mismo identificador al mismo tiempo.
Si se produce un error en TraceLoggingRegister , el identificador del proveedor permanecerá sin registrar y todos los usos del identificador de proveedor serán seguros sin operaciones. En concreto, es una operación segura para llamar a TraceLoggingWrite o TraceLoggingUnregister con un identificador de proveedor no registrado.
Importante
Si el archivo DLL o el controlador llama a TraceLoggingRegister en un identificador de proveedor, debe llamar a TraceLoggingUnregister en ese identificador de proveedor antes de que se descargue el archivo DLL o el controlador. Si un archivo DLL se descarga sin llamar a TraceLoggingUnregister, el proceso puede bloquearse posteriormente. Si un controlador se descarga sin llamar a TraceLoggingUnregister, el sistema puede bloquearse posteriormente. La función TraceLoggingRegister establece una devolución de llamada de configuración ETW y TraceLoggingUnregister cancela la devolución de llamada. Si la devolución de llamada no se cancela y el módulo se descarga, se producirá un bloqueo la próxima vez que ETW intente invocar la devolución de llamada.
Advertencia
Si el controlador llama a TraceLoggingRegister y, a continuación, encuentra un error durante DriverEntry, debe llamar a TraceLoggingUnregister antes de devolver el error de DriverEntry. No se llamará a las rutinas de limpieza de controladores normales si el controlador devuelve un error de DriverEntry y si no se llama a TraceLoggingUnregister , el sistema se bloqueará.
TraceLoggingRegister hace lo siguiente:
- Llama a EventRegister para abrir la conexión a ETW.
- Si EventRegister se realiza correctamente, llama a TraceLoggingSetInformation con InformationClassEventProviderSetTraits para configurar el proveedor para la compatibilidad con TraceLogging.
Una llamada a TraceLoggingRegister es la misma que una llamada a TraceLoggingRegisterEx con NULL para la devolución de llamada y los parámetros de contexto . Use TraceLoggingRegisterEx si necesita recibir una devolución de llamada de habilitación de ETW cuando las sesiones habilitan o deshabilitan el proveedor.
Requisitos
| Requisito | Value |
|---|---|
| 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] |
| Encabezado | traceloggingprovider.h |
| Library | Advapi32.lib |