Función TraceMessageVa (evntrace.h)
Un proveedor de eventos basado en RegisterTraceGuids ("clásico") usa la función TraceMessageVa para enviar un evento basado en mensajes (WPP basado en TMF) a una sesión de seguimiento de eventos mediante parámetros va_list.
Sintaxis
ULONG TraceMessageVa(
[in] TRACEHANDLE LoggerHandle,
[in] ULONG MessageFlags,
[in] LPCGUID MessageGuid,
[in] USHORT MessageNumber,
[in] va_list MessageArgList
);
Parámetros
[in] LoggerHandle
Identificador de 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íficos del proveedor del evento. La sección de datos específica del proveedor del evento solo contendrá datos para las marcas que se establecen. La lista de variables de los datos de argumento seguirá esta información. Este parámetro puede ser uno o más de los siguientes valores.
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.
La información se incluye en los datos del evento en el orden siguiente:
- Número de secuencia
- GUID de clase de seguimiento de eventos
- Marca de tiempo
- Identificador de subproceso
- Identificador de proceso
[in] MessageGuid
GUID de clase que identifica el mensaje de seguimiento de eventos.
[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.
[in] MessageArgList
Lista de argumentos de variable que se van a anexar al mensaje. 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 con 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 supere 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. En la tabla siguiente se incluyen 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 hay más búferes 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 de 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 a esta función directamente. Los proveedores de WPP usan funciones contenedoras generadas por tracewpp.exe en lugar de llamar a las API de ETW.
Si no necesita acceder a la funcionalidad de seguimiento de mensajes desde una función contenedora, puede llamar a la versión TraceMessage 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 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 TRACE_MESSAGE_SYSTEMINFO.
Requisitos
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | evntrace.h |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |