Função EvtSubscribe (winevt.h)

Cria uma assinatura que receberá eventos atuais e futuros de um canal ou arquivo de log que corresponda aos critérios de consulta especificados.

Sintaxe

EVT_HANDLE EvtSubscribe(
  [in] EVT_HANDLE             Session,
  [in] HANDLE                 SignalEvent,
  [in] LPCWSTR                ChannelPath,
  [in] LPCWSTR                Query,
  [in] EVT_HANDLE             Bookmark,
  [in] PVOID                  Context,
  [in] EVT_SUBSCRIBE_CALLBACK Callback,
  [in] DWORD                  Flags
);

Parâmetros

[in] Session

Um identificador de sessão remota que a função EvtOpenSession retorna. Defina como NULL para assinar eventos no computador local.

[in] SignalEvent

O identificador para um objeto de evento que o serviço sinalizará quando novos eventos estiverem disponíveis que correspondam aos critérios de consulta. Esse parâmetro deverá ser NULL se o parâmetro De retorno de chamada não for NULL.

[in] ChannelPath

O nome do canal Administração ou Operacional que contém os eventos que você deseja assinar (não é possível assinar canais analíticos ou de depuração). O caminho será necessário se o parâmetro Query contiver uma consulta XPath; o caminho será ignorado se o parâmetro Query contiver uma consulta XML estruturada.

[in] Query

Uma consulta que especifica os tipos de eventos que você deseja que o serviço de assinatura retorne. Você pode especificar uma consulta XPath 1.0 ou uma consulta XML estruturada. Se o XPath contiver mais de 20 expressões, use uma consulta XML estruturada. Para receber todos os eventos, defina esse parâmetro como NULL ou "*".

[in] Bookmark

Um identificador para um indicador que identifica o ponto de partida da assinatura. Para obter um identificador de indicador, chame a função EvtCreateBookmark . Você deve definir esse parâmetro se o parâmetro Flags contiver o sinalizador EvtSubscribeStartAfterBookmark; caso contrário, NULL.

[in] Context

Um valor de contexto definido pelo chamador que o serviço de assinatura passará para o retorno de chamada especificado sempre que ele entregar um evento.

[in] Callback

Ponteiro para sua função de retorno de chamada EVT_SUBSCRIBE_CALLBACK que receberá os eventos de assinatura. Esse parâmetro deverá ser NULL se o parâmetro SignalEvent não for NULL.

[in] Flags

Um ou mais sinalizadores que especificam quando começar a assinar eventos. Por exemplo, se você especificar EvtSubscribeStartAtOldestRecord, o serviço recuperará todos os eventos atuais e futuros que correspondam aos critérios de consulta; no entanto, se você especificar EvtSubscribeToFutureEvents, o serviço retornará apenas eventos futuros que correspondam aos critérios de consulta. Para obter valores possíveis, consulte a enumeração EVT_SUBSCRIBE_FLAGS .

Valor retornado

Um identificador para a assinatura se tiver êxito; caso contrário, NULL. Se a função retornar NULL, chame a função GetLastError para obter o código de erro. Você deve chamar a função EvtClose com o identificador de assinatura quando terminar.

Comentários

Para cancelar a assinatura, passe o identificador de assinatura retornado para a função EvtClose .

Há dois modelos de assinatura: o modelo de pesquisa e o modelo de push. No modelo de push, você implementa um retorno de chamada de assinatura e define o parâmetro De retorno de chamada para sua implementação. O serviço chamará o retorno de chamada para cada evento que corresponda aos critérios de consulta (ou se ocorrer um erro).

No modelo de pesquisa, você cria um objeto de evento que o serviço sinaliza. Quando sinalizado, você chama a função EvtNext usando o identificador de assinatura para enumerar os eventos. Você deve chamar a função EvtClose em cada evento que enumerar. Em seguida, você redefine o objeto e aguarda o serviço sinalizar novamente. Esse processo se repete até que você cancele a assinatura.

Exemplos

Para obter um exemplo que mostra como usar essa função, consulte Assinando eventos.

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	winevt.h
Biblioteca	Wevtapi.lib
DLL	Wevtapi.dll

Confira também

EVT_SUBSCRIBE_CALLBACK

EvtQuery