Condividi tramite

Funzione TraceEvent (evntrace.h)

  • Articolo

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.

Nota

La maggior parte degli sviluppatori non chiamerà questa funzione. Questa API supporta ETW basato su MOF, ma ETW basato su MOF è deprecato a favore di ETW basato su manifesto. Inoltre, la maggior parte dei provider basati su MOF usa funzioni wrapper generate da MC.exe anziché chiamare direttamente le API ETW.

Prima che il provider possa chiamare questa funzione, il 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

   
Client minimo supportato Windows 2000 Professional [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione evntrace.h
Libreria Advapi32.lib
DLL Advapi32.dll

Vedi anche

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance