Función TraceMessage (evntrace.h)
Un proveedor de eventos basado en RegisterTraceGuids ("clásico") usa la función TraceMessage para enviar un evento basado en mensajes (WPP basado en TMF) a una sesión de seguimiento de eventos.
Sintaxis
ULONG TraceMessage(
[in] TRACEHANDLE LoggerHandle,
[in] ULONG MessageFlags,
[in] LPCGUID MessageGuid,
[in] USHORT MessageNumber,
...
);
Parámetros
[in] LoggerHandle
Controle la sesión de seguimiento de eventos que registra el evento. El proveedor obtiene el identificador cuando llama a la función GetTraceLoggerHandle en su implementación de ControlCallback .
[in] MessageFlags
Agrega información adicional al principio de la sección de datos específica del proveedor del evento. La sección de datos específica del proveedor del evento contendrá datos solo para las marcas establecidas. La lista de variables de datos de argumento seguirá esta información. Este parámetro puede ser uno o más de los siguientes valores.
TRACE_MESSAGE_COMPONENTID
Incluya el identificador de componente en el mensaje. El parámetro MessageGuid contiene el identificador de componente.
TRACE_MESSAGE_GUID
Incluya el GUID de la clase de seguimiento de eventos en el mensaje. El parámetro MessageGuid contiene el GUID de la clase de seguimiento de eventos.
TRACE_MESSAGE_SEQUENCE
Incluya un número de secuencia en el mensaje. El número de secuencia comienza en uno. Para usar esta marca, el controlador debe haber establecido el EVENT_TRACE_USE_GLOBAL_SEQUENCE o EVENT_TRACE_USE_LOCAL_SEQUENCE modo de archivo de registro al crear la sesión.
TRACE_MESSAGE_SYSTEMINFO
Incluya el identificador de subproceso y el identificador de proceso en el mensaje.
TRACE_MESSAGE_TIMESTAMP
Incluya una marca de tiempo en el mensaje.
TRACE_MESSAGE_COMPONENTID y TRACE_MESSAGE_GUID son mutuamente excluyentes.
La información se incluye en los datos del evento en el orden siguiente:
- Número de secuencia
- GUID de la clase de seguimiento de eventos (o identificador de componente)
- Marca de tiempo
- Identificador de subproceso
- Identificador de proceso
[in] MessageGuid
Guid de clase o identificador de componente que identifica el mensaje. Depende de si MessageFlags contiene la marca TRACE_MESSAGE_COMPONENTID o TRACE_MESSAGE_GUID .
[in] MessageNumber
Número que identifica de forma única cada aparición del mensaje. Debe definir el valor especificado para este parámetro; el valor debe ser significativo para la aplicación.
...
Lista de argumentos de variable que se van a anexar al mensaje. Use esta lista para especificar los datos de eventos específicos del proveedor. La lista debe estar compuesta de pares de argumentos como se indica a continuación.
- PVOID: puntero a los datos del argumento.
- size_t: tamaño de los datos del argumento, en bytes.
Finalice la lista mediante un par de argumentos que consta de un puntero a NULL y cero.
El autor de la llamada debe asegurarse de que la suma de los tamaños de los argumentos + 72 no supera el tamaño del búfer de la sesión de seguimiento de eventos.
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.
ERROR_INVALID_HANDLE
LoggerHandle es NULL o especifica el identificador de sesión del registrador de kernel nt.
ERROR_NOT_ENOUGH_MEMORY
La sesión se quedó sin búferes libres donde escribir. Esto puede ocurrir cuando las tasas de eventos son elevadas porque el subsistema del disco se sobrecarga o el número de búferes es demasiado pequeño. En lugar de bloquear hasta que más búferes estén disponibles, TraceMessage descarta el evento.
Windows 2000 y Windows XP: No se admite.
ERROR_OUTOFMEMORY
El evento se descarta porque, aunque el grupo de búferes no ha alcanzado su tamaño máximo, no hay suficiente memoria disponible para asignar un búfer adicional y no hay ningún búfer disponible para recibir el evento.
ERROR_INVALID_PARAMETER
MessageFlags contiene un valor que no es válido.
ERROR_MORE_DATA
Los datos de un único evento no pueden abarcar varios búferes. Un evento de seguimiento se limita al tamaño del búfer de la sesión de seguimiento de eventos menos el tamaño de la estructura EVENT_TRACE_HEADER .
Comentarios
Los proveedores de WPP basados en TMF llaman a esta función.
Nota:
La mayoría de los desarrolladores no llamarán directamente a esta función. Los proveedores de WPP usan funciones contenedoras generadas por tracewpp.exe en lugar de llamar a las API de ETW.
Si necesita acceder a la funcionalidad de seguimiento de mensajes desde una función contenedora, llame a la versión TraceMessageVa de esta función.
Los consumidores tendrán que usar la devolución de llamada eventCallback para recibir y procesar los eventos si el parámetro MessageFlags no contiene la marca TRACE_MESSAGE_GUID. Si no especifica la marca TRACE_MESSAGE_GUID, el consumidor no podrá usar EventClassCallback porque el miembro Header.Guid de la estructura de EVENT_TRACE no contendrá el GUID de la clase de seguimiento de eventos.
Tenga en cuenta que los miembros de las estructuras EVENT_TRACE y EVENT_TRACE_HEADER que corresponden a las marcas MessageFlags solo se establecen si se especifica la marca correspondiente. Por ejemplo, los miembros ThreadId y ProcessId de EVENT_TRACE_HEADER solo se rellenan si especifica la marca de TRACE_MESSAGE_SYSTEMINFO.
Requisitos
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | evntrace.h |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |