Condividi tramite


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

Vedi anche

EventActivityIdControl

EventRegister

EventWrite

EventWriteEx

Scrittura di eventi basati su manifesto.