Funzione TraceEventInstance (evntrace.h)
Un provider di eventi basato su RegisterTraceGuids ("classico") usa la funzione TraceEventInstance per inviare un evento strutturato a una sessione di traccia eventi con un identificatore di istanza.
L'evento usa un identificatore di istanza per associare l'evento a una transazione. Questa funzione può essere usata anche per tracciare relazioni gerarchici tra eventi correlati.
Sintassi
ULONG WMIAPI TraceEventInstance(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_INSTANCE_HEADER EventTrace,
[in] PEVENT_INSTANCE_INFO InstInfo,
[in] PEVENT_INSTANCE_INFO ParentInstInfo
);
Parametri
[in] TraceHandle
Gestire la sessione di traccia eventi che registra l'istanza dell'evento. Il provider ottiene l'handle quando chiama la funzione GetTraceLoggerHandle nell'implementazionedi ControlCallback .
[in] EventTrace
Puntatore a una struttura EVENT_INSTANCE_HEADER . I dati specifici dell'evento vengono facoltativamente aggiunti alla struttura. L'evento più grande che è possibile registrare è 64K. È necessario specificare i valori per i membri seguenti della struttura EVENT_INSTANCE_HEADER .
- Dimensione
- Flag
- RegHandle
A seconda della complessità delle informazioni fornite dal provider, è anche consigliabile specificare i valori per i membri seguenti.
- Class.Type
- Class.Level
Per tracciare relazioni gerarchico tra eventi correlati, impostare anche il membro ParentRegHandle .
[in] InstInfo
Puntatore a una struttura EVENT_INSTANCE_INFO , che contiene l'handle di registrazione per questa classe di traccia evento e l'identificatore dell'istanza. Usare la funzione CreateTraceInstanceId per inizializzare la struttura.
[in] ParentInstInfo
Puntatore a una struttura EVENT_INSTANCE_INFO , che contiene l'handle di registrazione per la classe di traccia dell'evento padre e il relativo identificatore di istanza. Usare la funzione CreateTraceInstanceId per inizializzare la struttura. Impostare su NULL se non si traccia una relazione gerarchica.
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_FLAGS
Il membro Flag del EVENT_INSTANCE_HEADER non contiene WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY
Memoria insufficiente per completare la chiamata alla funzione. Le cause per questo codice di errore sono descritte nella sezione Osservazioni seguenti.
ERROR_INVALID_PARAMETER
Una delle seguenti condizioni è vera:
- EventTrace è NULL.
- pInstInfo è NULL.
- I membri di pInstInfo sono NULL.
- TraceHandle è NULL.
- Il membro Size del EVENT_INSTANCE_HEADER non è corretto.
ERROR_INVALID_HANDLE
TraceHandle non è valido 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, TraceEvent 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_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_INSTANCE_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 L'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
- Deve chiamare la funzione RegisterTraceGuids per registrare se stessa e la classe di traccia eventi.
- Deve chiamare la funzione CreateTraceInstanceId per creare un identificatore di istanza per la classe di traccia eventi registrata.
- 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 entrambi. Il membro LogFileMode della struttura EVENT_TRACE_PROPERTIES passato a StartTrace definisce la posizione in cui viene inviato l'evento.
Gli eventi di traccia vengono scritti nell'ordine in cui si verificano.
Per tracciare eventi non correlati, usare la funzione TraceEvent .
Windows XP: Non funziona correttamente.
Esempio
Per un esempio di generazione di set correlati di eventi tramite CreateTraceInstanceId e TraceEventInstance, vedere Traccia delle istanze degli 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 |