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 |