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

Voir aussi

EVT_SUBSCRIBE_CALLBACK

EvtQuery