Funzione EventWriteString (evntprov.h)

Articolo
08/23/2023

Scrive un evento ETW che contiene una stringa come dati. Questa funzione non deve essere utilizzata.

Sintassi

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parametri

[in] RegHandle

Handle di registrazione del provider. L'handle proviene da EventRegister. L'evento generato userà il ProviderId associato all'handle.

[in] Level

Numero a 8 bit usato per descrivere la gravità o l'importanza di un evento.

Importante

ProviderId, Level e Keyword sono i mezzi principali per filtrare gli eventi. Altri tipi di filtro sono possibili, ma hanno un sovraccarico molto maggiore. Assegnare sempre un livello diverso da zero e una parola chiave a ogni evento.

Per informazioni dettagliate sul livello dell'evento, vedere EVENT_DESCRIPTOR .

[in] Keyword

Maschera a 64 bit usata per indicare l'appartenenza di un evento in un set di categorie di eventi.

Importante

Per informazioni dettagliate sulla parola chiave dell'evento , vedere EVENT_DESCRIPTOR .

[in] String

Stringa con terminazione NUL da scrivere come dati dell'evento.

Valore restituito

Restituisce ERROR_SUCCESS in caso di esito positivo o di 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 della sessione è troppo piccola per l'evento.
ERROR_NOT_ENOUGH_MEMORY: si verifica quando i buffer riempiti tentano di scaricare su disco, ma le operazioni di I/O del disco non vengono eseguite abbastanza velocemente. Ciò si verifica quando il disco è lento e il traffico degli eventi è elevato. Alla fine, non sono presenti più 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 finché un consumer in tempo reale non 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 essere eseguita e continuare a segnalare gli eventi anche se non è stato possibile scrivere un evento ETW, pertanto le compilazioni di versione devono in genere ignorare il codice di errore.

Commenti

Questa API non è utile e non deve essere usata.

La maggior parte degli strumenti di analisi ETW non supporta correttamente gli eventi di sola stringa senza un manifesto.
Senza un manifesto, le informazioni importanti sull'evento (ad esempio il nome del provider, l'ID evento e il nome dell'evento) non sono disponibili, pertanto gli eventi risultanti sono difficili da usare anche quando lo strumento di analisi supporta eventi solo stringa.
Con un manifesto, questa funzione si comporta quasi esattamente come il codice di un evento basato su manifesto con un singolo campo stringa. Tuttavia, l'evento basato su manifesto è più supportato dagli strumenti di analisi delle tracce. Inoltre, il codice generato da MC.exe per un evento con un singolo campo stringa è più efficiente rispetto alla funzione EventWriteString .

Invece di usare questa API, considerare le alternative seguenti:

Usare TraceLoggingProvider.h per scrivere eventi ben supportati dagli strumenti di analisi ETW, lavorare senza un manifesto e includere metadati come il nome del provider e il nome dell'evento.
Scrivere un manifesto di strumentazione. Creare un evento semplice con un singolo valore stringa con terminazione NUL. È possibile scrivere e raccogliere eventi anche senza un manifesto. Sarà necessario solo il manifesto per decodificare la traccia raccolta.

EventWriteString scrive un evento con un payload di dati costituito dalla stringa specificata. Questa API è quasi equivalente al codice seguente:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

L'evento risultante è uguale a qualsiasi altro evento generato da EventWrite , ad eccezione del fatto che l'evento risultante ha il flag EVENT_HEADER_FLAG_STRING_ONLY impostato (vedere EVENT_HEADER per informazioni sui flag di evento).

Si noti che l'evento viene scritto con ID, Version, Opcode, Task e Channel impostato su 0.

Si noti che l'evento usa l'ID attività del thread corrente.

Gli strumenti di analisi ETW che conoscono il flag EVENT_HEADER_FLAG_STRING_ONLY possono estrarre il valore stringa anche quando il decodificatore non riesce a individuare altre informazioni di decodifica per il provider di eventi. Tuttavia, senza un manifesto, gli strumenti non saranno in grado di determinare il nome del provider dell'evento.

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

Vedi anche

EventWrite

TraceLoggingProvider.h

Condividi tramite