Condividi tramite

Funzione TraceMessageVa (evntrace.h)

  • Articolo

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

Sintassi

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

Parametri

[in] LoggerHandle

Handle per la sessione di traccia eventi che registra l'evento. Il provider ottiene l'handle quando chiama la funzione GetTraceLoggerHandle nell'implementazionecontrolCallback .

[in] MessageFlags

Aggiunge informazioni aggiuntive all'inizio della sezione dei dati specifici del provider dell'evento. La sezione dei dati specifici del provider dell'evento conterrà i dati solo per i 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_GUID: includere il GUID della classe di traccia di eventi nel messaggio. Il parametro MessageGuid contiene il GUID della classe di traccia eventi.

  • TRACE_MESSAGE_SEQUENCE: includere un numero di sequenza nel messaggio. Il numero di sequenza inizia da uno. Per usare questo flag, è necessario che il controller abbia impostato il EVENT_TRACE_USE_GLOBAL_SEQUENCE o EVENT_TRACE_USE_LOCAL_SEQUENCE modalità di 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.

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

  • Numero di sequenza
  • GUID della classe di traccia di evento
  • Timestamp
  • Identificatore del thread
  • Identificatore del processo

[in] MessageGuid

GUID della classe che identifica il messaggio di traccia dell'evento.

[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.

[in] MessageArgList

Elenco di argomenti variabili da aggiungere al messaggio. 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 garantire 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 viene ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. La tabella seguente include alcuni errori comuni e le relative cause.

  • ERROR_INVALID_HANDLE

    LoggerHandle è NULL o specifica l'handle di sessione del logger del kernel NT.

  • 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. Invece di 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 non è necessario accedere alla funzionalità di traccia dei messaggi da una funzione wrapper, è possibile chiamare la versione TraceMessage di questa funzione.

I consumer dovranno usare il callback EventCallback per ricevere ed elaborare gli eventi se il parametro MessageFlags non contiene il flag 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.Guid della struttura EVENT_TRACE non conterrà il GUID della classe di traccia di evento.

Si noti che i membri della 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 [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione evntrace.h
Libreria Advapi32.lib
DLL Advapi32.dll

Vedi anche

Traceevent

TraceEventInstance

TraceMessage