Função EtwWrite (wdm.h)
A função EtwWrite é uma função de rastreamento para publicar eventos no código do driver no modo kernel.
Sintaxe
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[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, 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.
[in] UserDataCount
O número de estruturas de EVENT_DATA_DESCRIPTOR em UserData.
[in, optional] UserData
Um ponteiro para a matriz de estruturas de EVENT_DATA_DESCRIPTOR.
Valor de retorno
Se o evento tiver sido publicado com êxito, EtwWrite retornará STATUS_SUCCESS.
Se o ponteiro para o identificador de registro do provedor de eventos for inválido, EtwWrite retornará STATUS_INVALID_HANDLE. O provedor de eventos deve ser registrado antes que etwWrite seja chamado. EtwWrite também podem retornar STATUS_INVALID_HANDLE se não for possível registrar o evento em log.
Se o número de estruturas de EVENT_DATA_DESCRIPTOR especificadas em UserDataCount for maior que o máximo permitido (128), etwWrite retornará STATUS_INVALID_PARAMETER.
Se ActivityID for especificado, mas não houver memória suficiente disponível para registrar os dados associados ao evento, EtwWrite retornará STATUS_NO_MEMORY.
Se o provedor não estiver habilitado para nenhuma sessão, EtwWrite retornará STATUS_SUCCESS e os eventos não serão registrados.
Os eventos podem ser perdidos por vários motivos; por exemplo, se a taxa de eventos for muito alta ou se o tamanho do evento for maior que o tamanho do buffer. Nesses casos, o contador EventsLost, membro da estrutura EVENT_TRACE_PROPERTIES do agente correspondente, é atualizado com o número de eventos que não foram registrados.
Observações
A função EtwWrite é o equivalente do modo kernel da função EventWrite do modo de usuário. 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.
Antes de chamar função EtwWrite para publicar um evento, registre o provedor com etwRegister. Nenhuma chamada de rastreamento deve ser feita que esteja fora do código delimitado pelas funções EtwRegister e EtwUnregister. Para obter o melhor desempenho, você pode chamar a função EtwRegister em sua rotina de DriverEntry e a função EtwUnregister em sua rotina de driverunload.
Se você estiver usando o parâmetro UserData opcional na função EtwWrite para registrar dados de eventos adicionais em log, poderá usar a macro EventDataDescCreate para simplificar a criação das estruturas de EVENT_DATA_DESCRIPTOR. O exemplo a seguir usa a macro EventDataDescCreate para inicializar EVENT_DATA_DESCRIPTOR estruturas com o nome do dispositivo e seu status. A macro EventDataDescCreate armazena ponteiros para os dados (ou seja, ele não armazena cópias dos dados). Os ponteiros devem permanecer válidos até que a chamada para EtwWrite retorne.
Você pode chamar EtwWrite 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.
Exemplo
//
// Register the provider with ETW in DriverEntry
// Unregister the provider in DriverUnload
//
// Build the EVENT_DATA_DESCRIPTOR structures using
// the EventDataDescCreate macros
if (RegHandle != (REGHANDLE)NULL) {
//
// Log an Event with : DeviceNameLength
// DeviceName
// Status
//
EventDataDescCreate(&EventDataDescriptor[0],
(PVOID)&DeviceName.Length,
sizeof(USHORT));
EventDataDescCreate(&EventDataDescriptor[1],
(PVOID)DeviceName.Buffer,
DeviceName.Length);
EventDataDescCreate(&EventDataDescriptor[2],
(PVOID)&Status,
sizeof(ULONG));
EtwWrite(RegHandle, // Handle from EtwRegister
&StartEvent, // EventDescriptor
NULL, // Activity ID
3, // Number of data items
EventDataDescriptor); // Array of data descriptors
}
//
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | Qualquer nível (seção Ver Comentários.) |