Funzione TraceMessage (evntrace.h)

Articolo
08/23/2023

Un provider di eventi basato su RegisterTraceGuids ("classico") usa la funzione TraceMessage per inviare un evento WPP basato su messaggi a una sessione di traccia eventi.

Sintassi

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

Parametri

[in] LoggerHandle

Gestire la sessione di traccia eventi che registra l'evento. Il provider ottiene l'handle quando chiama la funzione GetTraceLoggerHandle nell'implementazione di ControlCallback .

[in] MessageFlags

Aggiunge altre informazioni all'inizio della sezione dei dati specifici del provider dell'evento. La sezione dati specifici del provider dell'evento conterrà dati solo per tali flag impostati. L'elenco di variabili dei dati dell'argomento seguirà queste informazioni. Questo parametro può essere uno o più dei valori seguenti.

TRACE_MESSAGE_COMPONENTID

Includere l'identificatore del componente nel messaggio. Il parametro MessageGuid contiene l'identificatore del componente.
TRACE_MESSAGE_GUID

Includere il GUID della classe di traccia dell'evento nel messaggio. Il parametro MessageGuid contiene il GUID della classe di traccia dell'evento.
TRACE_MESSAGE_SEQUENCE

Includere un numero di sequenza nel messaggio. Il numero di sequenza inizia con uno. Per usare questo flag, il controller deve avere impostato la EVENT_TRACE_USE_GLOBAL_SEQUENCE o EVENT_TRACE_USE_LOCAL_SEQUENCE modalità file di log durante la creazione della sessione.
TRACE_MESSAGE_SYSTEMINFO

Includere l'identificatore del thread e l'identificatore del processo nel messaggio.
TRACE_MESSAGE_TIMESTAMP

Includere un timestamp nel messaggio.

TRACE_MESSAGE_COMPONENTID e TRACE_MESSAGE_GUID si escludono a vicenda.

Le informazioni sono incluse nei dati dell'evento nell'ordine seguente:

Numero di sequenza
GUID della classe di traccia eventi (o identificatore del componente)
Timestamp
Identificatore di thread
Identificatore di processo

[in] MessageGuid

GUID di classe o ID componente che identifica il messaggio. Dipende se MessageFlags contiene il flag TRACE_MESSAGE_COMPONENTID o TRACE_MESSAGE_GUID .

[in] MessageNumber

Numero che identifica in modo univoco ogni occorrenza del messaggio. È necessario definire il valore specificato per questo parametro; il valore deve essere significativo per l'applicazione.

...

Elenco di argomenti variabili da aggiungere al messaggio. Usare questo elenco per specificare i dati di evento specifici del provider. L'elenco deve essere composto da coppie di argomenti come indicato di seguito.

PVOID: puntatore ai dati dell'argomento.
size_t: dimensioni dei dati dell'argomento, in byte.

Terminare l'elenco usando una coppia di argomenti costituita da un puntatore a NULL e zero.

Il chiamante deve assicurarsi che la somma delle dimensioni degli argomenti + 72 non superi le dimensioni del buffer della sessione di traccia eventi.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. Di seguito sono riportati alcuni errori comuni e le relative cause.

ERROR_INVALID_HANDLE

LoggerHandle è NULL o specifica l'handle di sessione NT Kernel Logger.
ERROR_NOT_ENOUGH_MEMORY

Sono stati esauriti i buffer liberi in cui scrivere per la sessione. Questa situazione può verificarsi in caso di frequenze di evento elevate perché il sottosistema del disco è sovraccarico o il numero di buffer è insufficiente. Anziché bloccare fino a quando non diventano disponibili più buffer, TraceMessage elimina l'evento.

Windows 2000 e Windows XP: Non supportato.
ERROR_OUTOFMEMORY

L'evento viene rimosso perché, anche se il pool di buffer non ha raggiunto le dimensioni massime, la memoria disponibile non è sufficiente per allocare un buffer aggiuntivo e non è disponibile alcun buffer per ricevere l'evento.
ERROR_INVALID_PARAMETER

MessageFlags contiene un valore non valido.
ERROR_MORE_DATA

I dati di un singolo evento non possono estendersi su più buffer. Un evento di traccia è limitato alle dimensioni del buffer della sessione di traccia eventi meno le dimensioni della struttura EVENT_TRACE_HEADER .

Commenti

I provider WPP basati su TMF chiamano questa funzione.

Nota

La maggior parte degli sviluppatori non chiamerà direttamente questa funzione. I provider WPP usano funzioni wrapper generate da tracewpp.exe anziché chiamare LE API ETW.

Se è necessario accedere alle funzionalità di traccia dei messaggi da una funzione wrapper, chiamare la versione TraceMessageVa di questa funzione.

I consumer dovranno usare il callback EventCallback per ricevere ed elaborare gli eventi se il parametro MessageFlags non contiene il flag di TRACE_MESSAGE_GUID. Se non si specifica il flag di TRACE_MESSAGE_GUID, il consumer non sarà in grado di usare EventClassCallback perché il membro Header.Guiddella struttura EVENT_TRACE non conterrà il GUID della classe di traccia dell'evento.

Si noti che i membri delle EVENT_TRACE e delle strutture EVENT_TRACE_HEADER corrispondenti ai flag MessageFlags vengono impostati solo se viene specificato il flag corrispondente. Ad esempio, i membri ThreadId e ProcessId di EVENT_TRACE_HEADER vengono popolati solo se si specifica il flag di TRACE_MESSAGE_SYSTEMINFO.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	evntrace.h
Libreria	Advapi32.lib
DLL	Advapi32.dll

Vedi anche

Traceevent

TraceEventInstance

TraceMessageVa

Condividi tramite