Função de retorno de chamada PENABLECALLBACK (evntprov.h)

Os provedores de eventos ETW opcionalmente definem uma função EnableCallback para receber notificações de alteração de configuração. O tipo PENABLECALLBACK define um ponteiro para essa função de retorno de chamada. EnableCallback é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Parâmetros

[in] SourceId

GUID especificado pelo chamador que está habilitando ou desabilitando o provedor.

O valor vem do parâmetro SourceId de EnableTraceEx ou do campo SourceId do ENABLE_TRACE_PARAMETERS que é passado para EnableTraceEx2.

Observação

SourceId é o valor que a sessão especifica na chamada para a API EnableTraceEx ou EnableTraceEx2. Ele pode ou não ser o mesmo que o GUID da sessão.

SourceId será definido como GUID_NULL em vários cenários em que a notificação não tem um identificador de origem. Por exemplo, isso pode ocorrer quando uma sessão de rastreamento habilitou o provedor antes do provedor ser iniciado, quando o provedor está parando ou quando um controlador de rastreamento chama uma API EnableTrace sem especificar uma SourceId.

[in] IsEnabled

Indica o ControlCode correspondente a esta notificação. Esse valor pode ser um dos seguintes:

Valor	Significado
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	Nenhuma sessão habilitou o provedor.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	Uma ou mais sessões habilitaram o provedor.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	Uma sessão está solicitando que o provedor registre suas informações de estado. O provedor normalmente responderá escrevendo eventos que contêm o estado do provedor.

Observação

O valor de IsEnabled pode não ser o mesmo que o ControlCode passado para a API EnableTrace que disparou esse evento. Por exemplo, se duas sessões habilitaram esse provedor e uma sessão desabilitar esse provedor chamando EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), o provedor receberá uma notificação com IsEnabled definida EVENT_CONTROL_CODE_ENABLE_PROVIDER como porque o provedor ainda está habilitado pela outra sessão.

Depois de receber uma notificação de DISABLE_PROVIDER , um provedor pode otimizar seu desempenho desabilitando todos os eventos. Depois de receber uma notificação de ENABLE_PROVIDER , um provedor deve habilitar a gravação de eventos. Ele também pode otimizar seu desempenho registrando os valores dos filtros Level, MatchAnyKeyword e MatchAllKeyword e, em seguida, apenas gravando os eventos que passam pelos filtros (conforme descrito em comentários). Depois de receber uma notificação de CAPTURE_STATE , um provedor pode tomar qualquer ação que pareça apropriada, normalmente escrevendo eventos que descrevem a configuração ou o estado do componente.

Um provedor deve ignorar notificações com valores IsEnabled que não reconhece nem dá suporte.

[in] Level

Um valor que especifica a verbosidade dos eventos que o provedor deve gravar. Quando invocado com o código de controle EVENT_CONTROL_CODE_ENABLE_PROVIDER, o provedor deve registrar o valor Level e, posteriormente, ignorar eventos em que o nível de verbosidade do evento é maior que o Nível registrado, ou seja, um evento só deve ser gravado se o nível de detalhamento do evento for maior que o Nível registrado, ou seja, um evento só deverá ser gravado se

eventDescriptor.Level <= recorded.Level

O Nível na notificação é o máximo dos níveis especificados pelos controladores de rastreamento em chamadas para EnableTrace, EnableTraceEx ou EnableTraceEx2 usando o GUID desse provedor de eventos. Em outras palavras, se várias sessões estiverem gravando eventos desse provedor de eventos em diferentes níveis de detalhamento, o parâmetro Level para a notificação EnableCallback será definido como o mais alto (mais detalhado) dos níveis.

[in] MatchAnyKeyword

Um valor bitmask que especifica categorias de eventos que o provedor deve gravar. Quando invocado com o código de controle EVENT_CONTROL_CODE_ENABLE_PROVIDER, o provedor deve registrar o valor MatchAnyKeyword e, posteriormente, ignorar eventos em que o palavra-chave do evento não é zero e não tem nenhum dos bits do MatchAnyKeyword gravado, ou seja, um evento só deve ser gravado se

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

O MatchAnyKeyword na notificação é a união (OR) das palavras-chave match-any-keywords (habilitar sinalizadores) especificadas pelos controladores de rastreamento em chamadas para EnableTrace, EnableTraceEx e EnableTraceEx2 para o GUID desse provedor de eventos. Em outras palavras, se várias sessões estiverem gravando eventos desse provedor de eventos com diferentes filtros match-any-palavra-chave, o parâmetro MatchAnyKeyword para a notificação EnableCallback será definido como bit a bit dosOR filtros match-any-palavra-chave das sessões.

MatchAllKeyword

Um valor bitmask que especifica categorias de eventos que o provedor deve gravar. Quando notificado com o código de controle EVENT_CONTROL_CODE_ENABLE_PROVIDER, o provedor deve registrar o valor MatchAllKeyword e, posteriormente, ignorar eventos em que o palavra-chave do evento não é zero e não tem todos os bits do MatchAllKeyword gravado, ou seja, um evento só deve ser gravado se

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

O MatchAllKeyword na notificação é a disjunção (AND) das palavras-chave match-all especificadas pelos controladores de rastreamento em chamadas para EnableTraceEx e EnableTraceEx2 para o GUID desse provedor de eventos. Em outras palavras, se várias sessões estiverem gravando eventos desse provedor de eventos com diferentes filtros match-all-palavra-chave, o parâmetro MatchAllKeyword para a notificação EnableCallback será definido como bit a bitAND dos filtros match-all-palavra-chave das sessões.

[in, optional] FilterData

Um ponteiro para um EVENT_FILTER_DESCRIPTOR com dados de filtro para o provedor de eventos.

Cada sessão pode especificar apenas um filtro. O descritor de filtro na notificação de retorno de chamada conterá um filtro de cada sessão que especificou dados de filtro ao habilitar o provedor.

Os dados de filtro são válidos somente no retorno de chamada. Os provedores devem fazer uma cópia local dos dados se os dados forem necessários após o retorno de chamada retornar.

[in, optional] CallbackContext

Contexto para o retorno de chamada. Esse é o valor do parâmetro CallbackContext que foi usado quando o provedor de eventos chamado EventRegister.

Valor retornado

Nenhum

Comentários

Os provedores de eventos ETW que precisam de notificações de alteração de configuração devem fornecer um ponteiro para sua implementação EnableCallback quando se registrarem por meio de EventRegister. O ETW invocará a função EnableCallback do provedor quando uma alteração for feita na configuração de uma sessão de rastreamento que envolve o provedor. Por exemplo, quando um controlador de sessão de rastreamento configura um rastreamento por meio de EnableTraceEx2 ou interrompe um rastreamento via ControlTrace, o ETW chamará a função EnableCallback do provedor com a configuração atualizada resultante.

Observação

A maioria dos provedores de eventos não implementará EnableCallback diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que fornece sua própria implementação EnableCallback e encapsula as chamadas para EventRegister, EventWrite e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto. A estrutura ETW normalmente implementa uma função EnableCallback que registra os valores , e MatchAllKeyword da LevelMatchAnyKeywordnotificação, e a estrutura usa automaticamente os valores registrados para filtrar eventos. A estrutura ETW geralmente dá suporte à invocação de um retorno de chamada fornecido pelo usuário se o usuário exigir tratamento de notificação personalizado. Por exemplo, TraceLoggingProvider.h permite que um retorno de chamada de notificação seja especificado por meio de TraceLoggingRegisterEx.

Importante

A função EnableCallback do provedor deve ser o mais simples possível. Ele deve registrar as informações necessárias e retornar rapidamente. Uma função de retorno de chamada de longa execução pode causar atrasos nas APIs de controle de sessão do ETW, como EnableTraceEx2 ou ControlTrace. A função de retorno de chamada não deve fazer nada que exija o bloqueio do carregador do processo, ou seja, ela não deve chamar loadLibrary ou FreeLibrary direta ou indiretamente. A função de retorno de chamada não deve bloquear em bloqueios. A função de retorno de chamada poderá causar um deadlock se bloquear em bloqueios ou se invocar as APIs de controle de sessão do ETW, como StartTrace, ControlTrace ou EnableTrace.

O retorno de chamada de notificação permite que o provedor de eventos seja executado com mais eficiência porque o provedor pode executar seu próprio acompanhamento do nível, palavras-chave e outros filtros. Ao acompanhar os filtros, o provedor pode ignorar com eficiência eventos que não estão habilitados (ou seja, o provedor não precisa preparar os dados do evento ou chamar EventWrite para eventos que não são necessários para nenhuma sessão de rastreamento).

Observe que o rastreamento de filtro não é necessário para a operação correta de um provedor: o ETW fornece funções EventEnabled e EventProviderEnabled que um provedor pode usar e as APIs EventWrite do ETW ignorarão silenciosamente quaisquer eventos desabilitados. No entanto, o rastreamento de filtro implementado pelo provedor pode ser mais eficiente do que as chamadas para EventEnabled ou EventProviderEnabled.

O retorno de chamada de notificação também permite que o provedor manipule solicitações de "estado de captura" de sessões de rastreamento. As solicitações de estado de captura normalmente são enviadas por uma sessão de rastreamento quando ela começa a gravar eventos de um provedor. Se houver suporte para o estado de captura por um provedor, ele poderá responder à solicitação de estado de captura registrando informações de estado em log, por exemplo, informações de configuração ou estatísticas resumidas sobre a operação do componente antes da solicitação.

O valor de Nível que o ETW passa para o retorno de chamada é o valor de nível mais alto (mais detalhado) especificado para esse provedor de eventos por qualquer sessão de rastreamento em execução. Por exemplo, se a sessão A tiver habilitado esse provedor para eventos de aviso (nível 3) e a sessão B habilitar o provedor para eventos críticos (nível 1), o valor de Nível para o retorno de chamada será 3, não 1.

Da mesma forma, os valores MatchAnyKeyword e MatchAllKeyword são valores compostos calculados a partir da configuração de todas as sessões que habilitaram o provedor de eventos. MatchAnyKeyword é o OR das configurações EnableFlags/MatchAnyKeyword das sessões. MatchAllKeyword é o AND das configurações de MatchAllKeyword das sessões.

Se a função EnableCallback do provedor capturou o estado Enabled, Level, MatchAnyKeyword e MatchAllKeyword do provedor, o provedor poderá determinar se um evento deve ser gravado usando uma função como a seguinte:

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Requisitos

Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	evntprov.h

Confira também

EventRegister

EnableTrace

EnableTraceEx2