Funzione EtwWriteEx (wdm.h)
La funzione EtwWriteEx è una funzione di traccia per la pubblicazione di eventi che supportano il filtro nel codice del driver in modalità kernel.
Sintassi
NTSTATUS EtwWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parametri
[in] RegHandle
Puntatore all'handle di registrazione del provider di eventi, restituito dalla funzione EtwRegister se la registrazione del provider di eventi ha esito positivo.
[in] EventDescriptor
Puntatore alla struttura EVENT_DESCRIPTOR.
[in] Filter
Identificatori dell'istanza che identificano la sessione in cui l'evento non verrà scritto. Ovvero, il valore è una maschera di sessioni che devono essere escluse dalla registrazione (filtrato). Usare un OR bit per bit per specificare più identificatori. Impostare su zero se non si supportano filtri o se l'evento viene scritto in tutte le sessioni (nessun filtro non è riuscito). Per informazioni su come ottenere l'identificatore per una sessione, vedere il parametro FilterData del EtwEnableCallback callback.
[in] Flags
Riservato. Deve essere zero (0).
[in, optional] ActivityId
Identificatore che indica l'attività associata all'evento. Il ActivityID consente di raggruppare gli eventi correlati e viene usato nella traccia end-to-end. Se NULL, ETW ottiene l'identificatore dalla risorsa di archiviazione locale del thread. Per informazioni dettagliate su come ottenere questo identificatore, vedere EtwActivityIdControl.
[in, optional] RelatedActivityId
Identificatore dell'attività del componente precedente. Usare questo parametro per collegare gli eventi del componente agli eventi del componente precedente. Per ottenere l'identificatore dell'attività impostato per il componente precedente, vedere le descrizioni per il parametro ControlCode della funzione EtwActivityIdControl.
[in] UserDataCount
Numero di strutture di EVENT_DATA_DESCRIPTOR in UserData. Il numero massimo è 128.
[in, optional] UserData
Puntatore alla matrice di strutture EVENT_DATA_DESCRIPTOR. Impostare questo parametro su NULL se UserDataCount è zero. I dati devono essere nell'ordine specificato nel manifesto.
Valore restituito
Restituisce ERROR_SUCCESS se ha esito positivo o uno dei valori seguenti in caso di errore.
Osservazioni
La funzione EtwWriteEx è l'equivalente in modalità kernel della funzione EventWriteEx in modalità utente. I dati dell'evento scritti con questa funzione richiedono un manifesto. Il manifesto è incorporato nel provider, pertanto il provider deve essere disponibile per consentire a un consumer di utilizzare i dati. Per assicurarsi che sia presente un consumer per l'evento che si sta pubblicando, è possibile precedere la chiamata a EtwWrite con una chiamata a EtwEventEnabled o EtwProviderEnabled.
Usare i parametri ActivityId e RelatedActivityId quando si vogliono correlare eventi in componenti diversi in uno scenario di traccia end-to-end. Ad esempio, i componenti A, B e C eseguono operazioni su un'attività correlata e vogliono collegare i relativi eventi in modo che un consumer possa utilizzare tutti gli eventi correlati a tale attività.
È possibile chiamare EtwWriteEx in qualsiasi IRQL. Tuttavia, quando IRQL è maggiore di APC_LEVEL, tutti i dati passati al EtwWrite, EtwWriteEx, EtwWriteString, funzioni EtwWriteTransfer non devono essere visualizzabili. Ovvero, qualsiasi routine in modalità kernel in esecuzione in IRQL maggiore di APC_LEVEL non può accedere alla memoria paging. I dati passati al EtwWrite, EtwWriteEx, EtwWriteStringe funzioni EtwWriteTransfer devono risiedere nella memoria dello spazio di sistema, indipendentemente da ciò che è IRQL.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 7 |
| server minimo supportato | Windows Server 2008 R2 |
| piattaforma di destinazione | Universale |
| intestazione | wdm.h |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |