Função EtwWriteEx (wdm.h)
A função EtwWriteEx é uma função de rastreamento para eventos de publicação que dão suporte à filtragem no código do driver no 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 deve ser excluída 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 de seu etwEnableCallback retorno de chamada.
[in] Flags
Reservado. Deve ser zero (0).
[in, optional] ActivityId
O identificador que indica a atividade associada ao evento. O ActivityID fornece uma maneira de agrupar eventos relacionados e é usado no rastreamento de ponta a ponta. Se NULL, o ETW obterá o identificador do armazenamento local do thread. Para obter detalhes sobre como obter esse identificador, consulte etwActivityIdControl.
[in, optional] RelatedActivityId
Identificador de atividade do componente anterior. Use esse parâmetro para vincular os eventos do componente aos 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 em 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 devem estar na ordem especificada no manifesto.
Valor de retorno
Retorna ERROR_SUCCESS se tiver êxito ou um dos seguintes valores no erro.
Observações
A função EtwWriteEx é o equivalente do 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 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 for maior que APC_LEVEL, todos os dados passados para o EtwWrite, EtwWriteEx, EtwWriteString, etwWriteTransfer não devem ser pagináveis. Ou seja, qualquer rotina de modo kernel que esteja 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, EtwWriteStringe EtwWriteTransfer devem residir na memória do espaço do sistema, independentemente do que seja o IRQL.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 7 |
| servidor com suporte mínimo | Windows Server 2008 R2 |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |