Fonction QueryTraceA (evntrace.h)

  • Article

La fonction QueryTrace récupère les paramètres de propriété et les statistiques de session pour la session de suivi des événements spécifiée.

Cette fonction est obsolète. La fonction ControlTrace remplace cette fonction.

Syntaxe

ULONG WMIAPI QueryTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Paramètres

TraceHandle

Gérez la session de suivi d’événements à interroger, ou 0. Vous devez spécifier une TraceHandle autre que zéro si InstanceName a la valeur NULL. Ce paramètre sera utilisé uniquement si InstanceName a la valeur NULL. Le handle est retourné par StartTrace.

InstanceName

Nom de la session de suivi des événements à interroger ou NULL. Vous devez spécifier InstanceName si TraceHandle a la valeur 0.

Pour spécifier la session NT Kernel Logger, définissez InstanceNamesur KERNEL_LOGGER_NAME.

Properties

Pointeur vers une structure EVENT_TRACE_PROPERTIES initialisée.

Il vous suffit de définir le membre Wnode.BufferSize de la structure EVENT_TRACE_PROPERTIES . Vous pouvez utiliser les longueurs maximales du nom de session (1 024 caractères) et du nom maximal du fichier journal (1 024 caractères) pour calculer la taille de la mémoire tampon et les décalages s’ils ne sont pas connus.

Sur la sortie, les membres de structure contiennent les paramètres de propriété et les statistiques de session pour la session de suivi d’événements.

À compter de Windows 10, version 1703 : Pour de meilleures performances dans les scénarios inter-processus, vous pouvez maintenant passer le filtrage dans QueryTrace pour les enregistreurs d’événements privés à l’échelle du système. Vous devez transmettre la nouvelle structure EVENT_TRACE_PROPERTIES_V2 pour inclure les informations de filtrage. Pour plus d’informations, consultez Configuration et démarrage d’une session d’enregistreur d’événements privés .

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système. Voici quelques erreurs courantes et leurs causes.

  • ERROR_BAD_LENGTH

    Une des conditions suivantes est vraie :

    • Le membre Wnode.BufferSize de Properties spécifie une taille incorrecte.
    • Les propriétés n’ont pas suffisamment d’espace alloué pour contenir une copie du nom de session et du nom du fichier journal (le cas échéant).

  • ERROR_INVALID_PARAMETER

    Une des conditions suivantes est vraie :

    • Les propriétés ont la valeur NULL.
    • InstanceName et TraceHandle sont tous deux NULL.
    • InstanceName a la valeur NULL et TraceHandle n’est pas un handle valide.

  • ERROR_ACCESS_DENIED

    Seuls les utilisateurs exécutant des privilèges d’administration élevés, les utilisateurs du groupe Utilisateurs du journal des performances et les services s’exécutant en tant que LocalSystem, LocalService et NetworkService peuvent interroger des sessions de suivi d’événements. Pour accorder à un utilisateur restreint la possibilité d’interroger des sessions de suivi, ajoutez-les au groupe Utilisateurs du journal des performances ou consultez EventAccessControl.

    Windows XP et Windows 2000 : Tout le monde peut contrôler une session de suivi.

  • ERROR_WMI_INSTANCE_NOT_FOUND

    La session donnée n’est pas en cours d’exécution.

Remarques

Les contrôleurs de suivi d’événements appellent cette fonction.

Cette fonction est obsolète. Utilisez plutôt ControlTrace avec ControlCode défini sur EVENT_TRACE_CONTROL_QUERY.

Notes

L’en-tête evntrace.h définit QueryTrace comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

ControlTrace

QueryAllTraces