Função EtwWriteEx (wdm.h)
A função EtwWriteEx é uma função de rastreamento para publicar eventos que dão suporte à filtragem no código do driver do modo kernel.
Sintaxe
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
);
Parâmetros
[in] RegHandle
Um ponteiro para o identificador de registro do provedor de eventos, que é retornado pela função EtwRegister se o registro do provedor de eventos for bem-sucedido.
[in] EventDescriptor
Um ponteiro para a estrutura EVENT_DESCRIPTOR .
[in] Filter
Os identificadores de instância que identificam a sessão na qual o evento não será gravado. Ou seja, o valor é uma máscara de sessões que devem ser excluídas do registro em log (filtrada). Use um OR bit a bit para especificar vários identificadores. Defina como zero se você não der suporte a filtros ou se o evento estiver sendo gravado em todas as sessões (nenhum filtro falhou). Para obter informações sobre como obter o identificador de uma sessão, consulte o parâmetro FilterData do retorno de chamada EtwEnableCallback .
[in] Flags
Reservado. Deve ser zero (0).
[in, optional] ActivityId
O identificador que indica a atividade associada ao evento. A ActivityID fornece uma maneira de agrupar eventos relacionados e é usada no rastreamento de ponta a ponta. Se FOR NULL, o ETW obterá o identificador do armazenamento local do thread. Para obter detalhes sobre como obter esse identificador, consulte EtwActivityIdControl.
[in, optional] RelatedActivityId
O identificador de atividade do componente anterior. Use esse parâmetro para vincular os eventos do componente para eventos do componente anterior. Para obter o identificador de atividade que foi definido para o componente anterior, consulte as descrições do parâmetro ControlCode da função EtwActivityIdControl .
[in] UserDataCount
Número de estruturas de EVENT_DATA_DESCRIPTOR no UserData. O número máximo é 128.
[in, optional] UserData
Um ponteiro para a matriz de estruturas de EVENT_DATA_DESCRIPTOR. Defina esse parâmetro como NULL se UserDataCount for zero. Os dados precisam estar na ordem especificada no manifesto.
Retornar valor
Retorna ERROR_SUCCESS se tiver êxito ou um dos seguintes valores no erro.
Comentários
A função EtwWriteEx é o equivalente ao modo kernel da função EventWriteEx do modo de usuário. Os dados de evento gravados com essa função exigem um manifesto. O manifesto é inserido no provedor, portanto, o provedor deve estar disponível para um consumidor consumir os dados. Para garantir que haja um consumidor para o evento que você está publicando, você pode preceder a chamada para EtwWrite com uma chamada para EtwEventEnabled ou EtwProviderEnabled.
Use os parâmetros ActivityId e RelatedActivityId quando quiser relacionar eventos em diferentes componentes em um cenário de rastreamento de ponta a ponta. Por exemplo, os componentes A, B e C executam o trabalho em uma atividade relacionada e desejam vincular seus eventos para que um consumidor possa consumir todos os eventos relacionados a essa atividade.
Você pode chamar EtwWriteEx em qualquer IRQL. No entanto, quando IRQL é maior que APC_LEVEL, todos os dados passados para as funções EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer não devem ser pagináveis. Ou seja, qualquer rotina de modo kernel em execução no IRQL maior que APC_LEVEL não pode acessar a memória paginável. Os dados passados para as funções EtwWrite, EtwWriteEx, EtwWriteString e EtwWriteTransfer devem residir na memória do espaço do sistema, independentemente do que seja o IRQL.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 7 |
| Servidor mínimo com suporte | Windows Server 2008 R2 |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |