Função de retorno de chamada WMIDPREQUEST (evntrace.h)

Artigo
02/29/2024

Um provedor de eventos baseado em RegisterTraceGuids ("Clássico") implementa essa função para receber solicitações de habilitação ou desabilitação de notificação de controladores.

O tipo WMIDPREQUEST define um ponteiro para essa função de retorno de chamada. ControlCallback é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

WMIDPREQUEST Wmidprequest;

ULONG Wmidprequest(
  [in] WMIDPREQUESTCODE RequestCode,
       PVOID RequestContext,
       ULONG *BufferSize,
  [in] PVOID Buffer
)
{...}

Parâmetros

[in] RequestCode

Código da solicitação. Esse será um dos valores a seguir.

Valor	Significado
WMI_ENABLE_EVENTS	Habilita o provedor ou altera a configuração do provedor.
WMI_DISABLE_EVENTS	Desabilita o provedor.

RequestContext

Contexto definido pelo provedor. O provedor usa o parâmetro RequestContext de
RegisterTraceGuids para especificar o contexto.

BufferSize

Reservado para uso interno.

[in] Buffer

Ponteiro para uma estrutura WNODE_HEADER que contém informações sobre a sessão de rastreamento de eventos para a qual o provedor está sendo habilitado ou desabilitado.

Retornar valor

Você deverá retornar ERROR_SUCCESS se o retorno de chamada for bem-sucedido. Observe que o ETW ignora o valor retornado para essa função, exceto quando um controlador chama EnableTrace para habilitar um provedor e o provedor ainda não chamou RegisterTraceGuids. Quando isso ocorrer, RegisterTraceGuids retornará o valor retornado desse retorno de chamada se o registro tiver sido bem-sucedido.

Comentários

Essa função é especificada usando a função RegisterTraceGuids . Quando o controlador chama a função EnableTrace para habilitar, desabilitar ou alterar os sinalizadores ou o nível de habilitação, o ETW chama esse retorno de chamada. O provedor habilita ou desabilita a si mesmo com base no valor requestCode . Normalmente, o provedor usa esse valor para definir um sinalizador global para indicar seu estado habilitado.

O provedor define sua interpretação de ser habilitado ou desabilitado. Em geral, se um provedor estiver habilitado, ele gerará eventos, mas enquanto estiver desabilitado, ele não gerará.

O ETW não passa os sinalizadores de habilitação e habilita o nível que o controlador passa para a função EnableTrace para esse retorno de chamada. Para recuperar essas informações, chame as funções GetTraceEnableFlags e GetTraceEnableLevel , respectivamente.

Você também precisa recuperar o identificador de sessão nesse retorno de chamada para chamadas futuras. Para recuperar o identificador de sessão, chame a função GetTraceLoggerHandle .

Sua função de retorno de chamada não deve chamar nada que possa incorrer em LoadLibrary (mais especificamente, qualquer coisa que exija um bloqueio de carregador).

Exemplos

Para obter um exemplo de implementação de uma função ControlCallback , consulte Escrevendo eventos clássicos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	evntrace.h