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, che viene restituito dalla funzione EtwRegister se la registrazione del provider di eventi ha esito positivo.
[in] EventDescriptor
Puntatore alla struttura EVENT_DESCRIPTOR .
[in] Filter
Identificatori di 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 (filtrate). Usare un OR bit per bit per specificare più identificatori. Impostare su zero se non si supportano i 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 callback EtwEnableCallback .
[in] Flags
Riservato. Deve essere zero (0).
[in, optional] ActivityId
Identificatore che indica l'attività associata all'evento. 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 di attività del componente precedente. Utilizzare questo parametro per collegare gli eventi del componente agli eventi del componente precedente. Per ottenere l'identificatore di attività impostato per il componente precedente, vedere le descrizioni per il parametro ControlCode della funzione EtwActivityIdControl .
[in] UserDataCount
Numero di strutture 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.
Commenti
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 l'utilizzo dei dati da parte di un consumer. 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 desidera 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, i dati passati alle funzioni EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer non devono essere pageable. Ovvero, qualsiasi routine in modalità kernel in esecuzione in IRQL maggiore di APC_LEVEL non può accedere alla memoria di paging. I dati passati alle funzioni EtwWrite, EtwWriteEx, EtwWriteString e EtwWriteTransfer devono risiedere nella memoria dello spazio di sistema, indipendentemente dal valore di IRQL.
Requisiti
| 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 |