EvtSubscribe, fonction (winevt.h)
Crée un abonnement qui recevra les événements actuels et futurs à partir d’un canal ou d’un fichier journal qui correspondent aux critères de requête spécifiés.
Syntaxe
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
);
Paramètres
[in] Session
Handle de session à distance que la fonction EvtOpenSession retourne. Définissez la valeur NULL pour vous abonner aux événements sur l’ordinateur local.
[in] SignalEvent
Handle à un objet d’événement que le service signale lorsque de nouveaux événements qui correspondent à vos critères de requête sont disponibles. Ce paramètre doit avoir la valeur NULL si le paramètre De rappel n’a pas la valeur NULL.
[in] ChannelPath
Nom du canal Administration ou opérationnel qui contient les événements auxquels vous souhaitez vous abonner (vous ne pouvez pas vous abonner à des canaux analytiques ou de débogage). Le chemin d’accès est requis si le paramètre Query contient une requête XPath ; le chemin d’accès est ignoré si le paramètre Query contient une requête XML structurée.
[in] Query
Requête qui spécifie les types d’événements que vous souhaitez que le service d’abonnement retourne. Vous pouvez spécifier une requête XPath 1.0 ou une requête XML structurée. Si votre XPath contient plus de 20 expressions, utilisez une requête XML structurée. Pour recevoir tous les événements, définissez ce paramètre sur NULL ou « * ».
[in] Bookmark
Handle d’un signet qui identifie le point de départ de l’abonnement. Pour obtenir un handle de signet, appelez la fonction EvtCreateBookmark . Vous devez définir ce paramètre si le paramètre Flags contient l’indicateur EvtSubscribeStartAfterBookmark ; sinon, NULL.
[in] Context
Valeur de contexte définie par l’appelant que le service d’abonnement passera au rappel spécifié chaque fois qu’il remet un événement.
[in] Callback
Pointeur vers votre fonction de rappel EVT_SUBSCRIBE_CALLBACK qui recevra les événements d’abonnement. Ce paramètre doit avoir la valeur NULL si le paramètre SignalEvent n’est pas NULL.
[in] Flags
Un ou plusieurs indicateurs qui spécifient quand commencer à s’abonner aux événements. Par exemple, si vous spécifiez EvtSubscribeStartAtOldestRecord, le service récupère tous les événements actuels et futurs qui correspondent à vos critères de requête ; Toutefois, si vous spécifiez EvtSubscribeToFutureEvents, le service retourne uniquement les événements futurs qui correspondent à vos critères de requête. Pour connaître les valeurs possibles, consultez l’énumération EVT_SUBSCRIBE_FLAGS .
Valeur retournée
Un handle de l’abonnement en cas de réussite ; sinon, NULL. Si la fonction retourne NULL, appelez la fonction GetLastError pour obtenir le code d’erreur. Vous devez appeler la fonction EvtClose avec le handle d’abonnement lorsque vous avez terminé.
Remarques
Pour annuler l’abonnement, transmettez le handle d’abonnement retourné à la fonction EvtClose .
Il existe deux modèles d’abonnement : le modèle d’interrogation et le modèle push. Dans le modèle push, vous implémentez un rappel d’abonnement et définissez le paramètre Callback sur votre implémentation. Le service appelle votre rappel pour chaque événement qui correspond à vos critères de requête (ou si une erreur se produit).
Dans le modèle d’interrogation, vous créez un objet d’événement que le service signale. Une fois signalé, vous appelez la fonction EvtNext à l’aide du handle d’abonnement pour énumérer les événements. Vous devez appeler la fonction EvtClose sur chaque événement que vous énumérez. Vous réinitialisez ensuite l’objet et attendez que le service signale à nouveau. Ce processus se répète jusqu’à ce que vous annuliez l’abonnement.
Exemples
Pour obtenir un exemple qui montre comment utiliser cette fonction, consultez Abonnement aux événements.
Configuration requise
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winevt.h |
| Bibliothèque | Wevtapi.lib |
| DLL | Wevtapi.dll |