Funzione EventWriteTransfer (evntprov.h)
Scrive un evento ETW con un ID attività e un ID attività facoltativo.
Sintassi
ULONG EVNTAPI EventWriteTransfer(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[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, optional] ActivityId
Puntatore facoltativo a un ID attività a 128 bit per questo evento. Se non è NULL, EventWriteTransfer userà il valore specificato per l'ID attività dell'evento. Se si tratta di NULL, EventWriteTransfer userà l'ID attività del thread corrente.
Gli strumenti di elaborazione delle tracce possono usare l'ID attività dell'evento per organizzare gli eventi in gruppi denominati attività. Per altre informazioni sull'ID attività, vedere EventActivityIdControl.
[in, optional] RelatedActivityId
Puntatore facoltativo a un ID attività a 128 bit padre dell'attività dell'evento. Se non è NULL, EventWriteTransfer userà il valore specificato per l'ID attività correlato all'evento. Se si tratta di NULL, l'evento non avrà un ID attività correlato. L'ID attività correlato viene in genere impostato sull'evento START dell'attività (il primo evento dell'attività, registrato con Opcode = START).
Gli strumenti di elaborazione delle tracce possono usare l'ID attività correlata dell'evento per determinare la relazione tra le attività, ad esempio l'attività correlata è l'elemento padre dell'attività appena avviata. Per altre informazioni sull'ID attività correlato, vedere EventActivityIdControl.
[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 EventWriteTransfer . La maggior parte dei provider di eventi viene implementata usando un framework ETW che esegue il wrapping delle chiamate a EventRegister, EventWriteTransfer 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.
EventWriteTransfer 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 EventWriteTransfer.
EventWriteTransfer equivale a EventWriteEx con 0 per Filtro e 0 per flag.
Requisiti
| Requisito | Valore |
|---|---|
| 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 |