Funzione TraceMessage (evntrace.h)
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'implementazionedi 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 |