Función EvtSubscribe (winevt.h)

Crea una suscripción que recibirá eventos actuales y futuros de un canal o archivo de registro que coincida con los criterios de consulta especificados.

Sintaxis

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

Identificador de sesión remota que devuelve la función EvtOpenSession . Establezca en NULL para suscribirse a eventos en el equipo local.

[in] SignalEvent

Identificador de un objeto de evento que el servicio indicará cuando haya nuevos eventos disponibles que coincidan con los criterios de consulta. Este parámetro debe ser NULL si el parámetro Callback no es NULL.

[in] ChannelPath

Nombre del canal de Administración o Operativo que contiene los eventos a los que desea suscribirse (no puede suscribirse a canales analíticos o de depuración). La ruta de acceso es necesaria si el parámetro Query contiene una consulta XPath; la ruta de acceso se omite si el parámetro Query contiene una consulta XML estructurada.

[in] Query

Consulta que especifica los tipos de eventos que desea que devuelva el servicio de suscripción. Puede especificar una consulta XPath 1.0 o una consulta XML estructurada. Si XPath contiene más de 20 expresiones, use una consulta XML estructurada. Para recibir todos los eventos, establezca este parámetro en NULL o "*".

[in] Bookmark

Identificador de un marcador que identifica el punto de partida de la suscripción. Para obtener un identificador de marcador, llame a la función EvtCreateBookmark . Debe establecer este parámetro si el parámetro Flags contiene la marca EvtSubscribeStartAfterBookmark; de lo contrario, NULL.

[in] Context

Valor de contexto definido por el autor de la llamada que el servicio de suscripción pasará a la devolución de llamada especificada cada vez que entrega un evento.

[in] Callback

Puntero a la función de devolución de llamada EVT_SUBSCRIBE_CALLBACK que recibirá los eventos de suscripción. Este parámetro debe ser NULL si el parámetro SignalEvent no es NULL.

[in] Flags

Una o varias marcas que especifican cuándo empezar a suscribirse a eventos. Por ejemplo, si especifica EvtSubscribeStartAtOldestRecord, el servicio recuperará todos los eventos actuales y futuros que coincidan con los criterios de consulta; Sin embargo, si especifica EvtSubscribeToFutureEvents, el servicio solo devuelve eventos futuros que coinciden con los criterios de consulta. Para obtener los valores posibles, consulte la enumeración EVT_SUBSCRIBE_FLAGS .

Valor devuelto

Identificador de la suscripción si se realiza correctamente; de lo contrario, NULL. Si la función devuelve NULL, llame a la función GetLastError para obtener el código de error. Debe llamar a la función EvtClose con el identificador de suscripción cuando haya terminado.

Comentarios

Para cancelar la suscripción, pase el identificador de suscripción devuelto a la función EvtClose .

Hay dos modelos de suscripción: el modelo de sondeo y el modelo de inserción. En el modelo de inserción, implementará una devolución de llamada de suscripción y establecerá el parámetro Callback en la implementación. El servicio llamará a la devolución de llamada para cada evento que coincida con los criterios de consulta (o si se produce un error).

En el modelo de sondeo, se crea un objeto de evento que señala el servicio. Cuando se señale, llame a la función EvtNext mediante el identificador de suscripción para enumerar los eventos. Debe llamar a la función EvtClose en cada evento que se enumera. A continuación, restablece el objeto y espera a que el servicio vuelva a indicar. Este proceso se repite hasta que se cancela la suscripción.

Ejemplos

Para ver un ejemplo que muestra cómo usar esta función, vea Suscribirse a eventos.

Requisitos

Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winevt.h
Library	Wevtapi.lib
Archivo DLL	Wevtapi.dll

Consulte también

EVT_SUBSCRIBE_CALLBACK

EvtQuery