Funzione TraceEvent (evntrace.h)

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

Sintassi

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Parametri

[in] TraceHandle

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

[in] EventTrace

Puntatore a una struttura EVENT_TRACE_HEADER . I dati specifici dell'evento vengono facoltativamente aggiunti alla struttura. L'evento più grande che è possibile registrare è leggermente inferiore a 64.000. È necessario specificare i valori per i membri seguenti della struttura EVENT_TRACE_HEADER .

• Dimensione
• Guid o GuidPtr
• Flag

A seconda della complessità delle informazioni fornite dal provider, è anche consigliabile specificare i valori per i membri seguenti.

• Class.Type
• Class.Level

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. Di seguito sono riportati alcuni errori comuni e le relative cause.

• ERROR_INVALID_FLAG_NUMBER

  Il membro Flags della struttura EVENT_TRACE_HEADER non è corretto.

• ERROR_INVALID_HANDLE

  TraceHandle non è valido 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, TraceEvent elimina l'evento.

  Aumentare il numero e la dimensione dei buffer per la sessione oppure ridurre il numero di eventi scritti o la loro dimensione.

  Windows 2000: 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

  Una delle seguenti condizioni è vera:

  • TraceHandle è NULL.
  • EventTrace è NULL.
  • Il membro Size della struttura EVENT_TRACE_HEADER non è corretto.

• 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 ETW basati su MOF chiamano questa funzione.

Prima che il provider possa chiamare questa funzione, il provider

• Deve chiamare la funzione RegisterTraceGuids per registrare se stessa e la classe di traccia dell'evento.
• Deve essere abilitato. Un controller chiama la funzione EnableTrace per abilitare un provider.

L'evento viene scritto in un file di log, inviato ai consumer di traccia eventi in tempo reale o in entrambi. Il membro LogFileMode della struttura EVENT_TRACE_PROPERTIES passato a StartTrace definisce dove viene inviato l'evento.

Gli eventi di traccia vengono scritti nell'ordine in cui si verificano.

Per tracciare un set di eventi correlati, utilizzare la funzione TraceEventInstance .

In Windows Vista è consigliabile usare la funzione EventWrite per registrare gli eventi.

Esempio

Per un esempio che usa TraceEvent, vedere Traccia eventi.

Requisiti

Vedi anche

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance