Función RegisterTraceGuidsW (evntrace.h)
La función RegisterTraceGuids registra un proveedor de seguimiento de eventos ETW clásico (estilo Windows 2000) y las clases de seguimiento de eventos que usa para generar eventos. Esta función también especifica la función de devolución de llamada que el sistema usa para habilitar y deshabilitar el seguimiento del proveedor.
Esta función está obsoleta. El nuevo código debe usar EventRegister para registrar un proveedor de seguimiento de eventos ETW de estilo Windows Vista (Crimson).
Sintaxis
ULONG WMIAPI RegisterTraceGuidsW(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCWSTR MofImagePath,
[in] LPCWSTR MofResourceName,
[out] PTRACEHANDLE RegistrationHandle
);
Parámetros
[in] RequestAddress
Puntero a una función ControlCallback que recibe una notificación cuando el proveedor está habilitado o deshabilitado por una sesión de seguimiento de eventos. La función EnableTrace desencadena esta devolución de llamada.
[in] RequestContext
Puntero a un contexto opcional definido por el proveedor que ETW pasa a la función especificada por RequestAddress.
[in] ControlGuid
GUID de control (id. de proveedor) del proveedor de registro.
[in] GuidCount
Número de elementos de la matriz TraceGuidReg . Si TraceGuidReg es NULL, establezca este parámetro en 0.
[in, out] TraceGuidReg
Puntero a una matriz de
TRACE_GUID_REGISTRATION estructuras.
Cada elemento identifica una categoría de eventos que proporciona el proveedor.
En la entrada, el miembro GUID de cada estructura contiene un GUID de clase de seguimiento de eventos asignado por el proveedor de registro. El GUID de clase identifica una categoría de eventos que proporciona el proveedor. Los proveedores usan el mismo GUID de clase para establecer el miembro Guid de EVENT_TRACE_HEADER al llamar a la función TraceEvent para registrar el evento.
En la salida, el miembro RegHandle recibe un identificador para el registro guid de clase del evento. Si el proveedor llama a la función TraceEventInstance , use el miembro RegHandle de TRACE_GUID_REGISTRATION para establecer el miembro RegHandle de EVENT_INSTANCE_HEADER.
Este parámetro puede ser NULL si el proveedor llama solo a la función TraceEvent para registrar eventos. Si el proveedor llama a la función TraceEventInstance para registrar eventos, este parámetro no puede ser NULL.
[in] MofImagePath
Este parámetro no se admite. Se establece en NULL. Debe usar Mofcomp.exe para registrar el recurso MOF durante la configuración de la aplicación. Para obtener más información, consulte Publicación del esquema de eventos.
Windows XP con SP1, Windows XP y Windows 2000: Puntero a una cadena opcional que especifica la ruta de acceso del archivo DLL o programa ejecutable que contiene el recurso especificado por MofResourceName. Este parámetro puede ser NULL si el proveedor de eventos y el consumidor usan otro mecanismo para compartir información sobre las clases de seguimiento de eventos usadas por el proveedor.
[in] MofResourceName
Este parámetro no se admite. Se establece en NULL. Debe usar Mofcomp.exe para registrar el recurso MOF durante la configuración de la aplicación. Para obtener más información, consulte Publicación del esquema de eventos.
Windows XP con SP1, Windows XP y Windows 2000: Puntero a una cadena opcional que especifica el recurso de cadena de MofImagePath. El recurso de cadena contiene el nombre del archivo MOF binario que describe las clases de seguimiento de eventos compatibles con el proveedor.
[out] RegistrationHandle
Recibe el identificador de registro del proveedor. Use el identificador devuelto al llamar a la función UnregisterTraceGuids .
Importante
Todos los identificadores de registro creados por un archivo DLL o controlador deben anularse el registro antes de que se descargue el archivo DLL o el controlador. Si el proveedor no está registrado, se producirá un bloqueo cuando ETW intente invocar la devolución de llamada del proveedor.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.
Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema. A continuación se muestran algunos errores comunes y sus causas.
Importante
Esta función también puede devolver el valor devuelto por ControlCallback si un controlador llama a EnableTrace para habilitar el proveedor y el proveedor aún no ha llamado a RegisterTraceGuids. Cuando esto ocurre, RegisterTraceGuids devolverá el valor devuelto de la devolución de llamada si el registro se realizó correctamente.
ERROR_INVALID_PARAMETER
Una de las siguientes condiciones se cumple:
- RequestAddress es NULL.
- ControlGuid es NULL.
- RegistrationHandle es NULL.
Windows XP y Windows 2000:TraceGuidReg son NULL o GuidCount es menor o igual que cero.
Comentarios
Nota
La mayoría de los desarrolladores no llamarán a esta función directamente. En su lugar, los desarrolladores suelen usar un marco ETW. Por ejemplo, WPP basado en TMF administra las llamadas a RegisterTraceGuids, TraceMessage y UnregisterTraceGuids en su nombre.
Esta función abre un identificador de proveedor de eventos clásico (estilo Windows 2000) que se puede usar para escribir eventos ETW de WPP basados en MOF y TMF a través de TraceEvent, TraceEventInstance, TraceMessage y TraceMessageVa.
Nota
Para abrir un identificador de proveedor de estilo de Windows Vista que escribe eventos ETW basados en manifiestos o basados en seguimiento mediante EventWrite, use EventRegister.
Si el ControlGuid del proveedor se ha registrado y habilitado previamente, los registros posteriores que hacen referencia al mismo ControlGuid se habilitan automáticamente.
Un proceso puede registrar hasta 1024 GUID de proveedor; sin embargo, debe limitar el número de proveedores que el proceso registra en uno o dos. Este límite incluye los registrados mediante esta función y la función EventRegister .
Antes de Windows Vista: No hay ningún límite para el número de proveedores que un proceso puede registrar.
Ejemplos
Para obtener un ejemplo que usa RegisterTraceGuids, consulte Escritura de eventos clásicos.
Nota
El encabezado evntrace.h define RegisterTraceGuids como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | evntrace.h |
| Library | Sechost.lib en Windows 8.1 y Windows Server 2012 R2; Advapi32.lib en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP |
| Archivo DLL | Sechost.dll en Windows 8.1 y Windows Server 2012 R2; Advapi32.dll en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP |