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

Vedi anche

EtwWrite

EventWrite

EventWriteEx