Funzione EventWrite (evntprov.h)
Scrive un evento ETW che usa l'ID attività del thread corrente.
Sintassi
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parametri
[in] RegHandle
Handle di registrazione del provider. L'handle proviene da EventRegister. L'evento generato userà providerId associato all'handle.
[in] EventDescriptor
EVENT_DESCRIPTOR con informazioni sugli eventi (metadati) inclusi ID, Versione, Livello, Parola chiave, Canale, Opcode e Attività.
Importante
ProviderId, Level and Keyword sono i mezzi principali per filtrare gli eventi. Altri tipi di filtro sono possibili, ma hanno un sovraccarico molto più elevato. Assegnare sempre un livello e una parola chiave non zero a ogni evento.
[in] UserDataCount
Numero di strutture EVENT_DATA_DESCRIPTOR in UserData. Il numero massimo è 128.
[in, optional] UserData
Matrice di strutture UserDataCountEVENT_DATA_DESCRIPTOR che descrivono i dati da includere nell'evento. UserData può essere NULL se UserDataCount è zero.
Ogni EVENT_DATA_DESCRIPTOR descrive un blocco di memoria da includere nell'evento. I blocchi specificati verranno concatenati per non avere riempimento o allineamento per formare il contenuto dell'evento. Se si usa la decodifica basata sul manifesto, il contenuto dell'evento deve corrispondere al layout specificato nel modello associato all'evento nel manifesto.
Valore restituito
Restituisce ERROR_SUCCESS se ha esito positivo o un codice di errore. I codici di errore possibili includono quanto segue:
- ERROR_INVALID_PARAMETER: uno o più parametri non sono validi.
- ERROR_INVALID_HANDLE: l'handle di registrazione del provider non è valido.
- ERROR_ARITHMETIC_OVERFLOW: la dimensione dell'evento è maggiore del massimo consentito (64 KB - intestazione).
- ERROR_MORE_DATA: la dimensione del buffer di sessione è troppo piccola per l'evento.
- ERROR_NOT_ENOUGH_MEMORY: si verifica quando i buffer riempiti tentano di scaricare su disco, ma non si verificano operazioni di I/O su disco abbastanza veloci. Ciò accade quando il disco è lento e il traffico di eventi è elevato. Alla fine, non sono presenti buffer gratuiti (vuoti) e l'evento viene eliminato.
- STATUS_LOG_FILE_FULL: il file di riproduzione in tempo reale è pieno. Gli eventi non vengono registrati nella sessione fino a quando un consumer in tempo reale utilizza gli eventi dal file di riproduzione.
Il codice di errore è destinato principalmente all'uso negli scenari di debug e diagnostica. La maggior parte del codice di produzione deve continuare a eseguire e continuare a segnalare eventi anche se non è stato possibile scrivere un evento ETW, pertanto le compilazioni di versione devono in genere ignorare il codice di errore.
Commenti
La maggior parte dei provider di eventi non chiamerà direttamente EventWrite . La maggior parte dei provider di eventi viene implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWrite e EventUnregister. Ad esempio, è possibile scrivere un manifesto evento e quindi usare il compilatore messaggi per generare codice C/C++ per gli eventi oppure è possibile usare TraceLogging per evitare la necessità di un manifesto.
EventWrite instrada l'evento alle sessioni di traccia appropriate in base al ProviderId (determinato da RegHandle), Level, Keyword e altre caratteristiche dell'evento. Se non vengono registrate sessioni di traccia, questa funzione non eseguirà alcuna operazione e restituirà ERROR_SUCCESS.
Per ridurre l'impatto sulle prestazioni degli eventi che non vengono registrati da alcuna sessione di traccia, è possibile chiamare EventEnabled per determinare se qualsiasi sessione di traccia sta registrando l'evento prima di preparare i dati e chiamare EventWrite.
EventWrite imposta l'ID attività dell'evento sull'ID attività del thread corrente. EventWrite non include un ID attività correlato nell'evento. Per specificare un ID attività diverso o per aggiungere un ID attività correlato, usare EventWriteTransfer.
EventWrite equivale a EventWriteEx con 0 per Filter, 0 per Flag, NULL per ActivityId e NULL per RelatedActivityId.
Requisiti
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntprov.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |