UpdateTraceA, fonction (evntrace.h)

  • Article

La fonction UpdateTrace met à jour le paramètre de propriété de la session de suivi d’événements spécifiée.

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

Syntaxe

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

Paramètres

TraceHandle

Gérez la session de suivi d’événements à mettre à jour, ou 0. Vous devez spécifier un TraceHandle différent de 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 d’événements à mettre à jour, 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.

Lors de l’entrée, les membres doivent spécifier les nouvelles valeurs pour les propriétés à mettre à jour. Pour plus d’informations sur les propriétés que vous pouvez mettre à jour, consultez Remarques.

Lors de la sortie, les membres de la structure contiennent les paramètres et statistiques mis à jour pour la session de suivi d’événements.

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. Le tableau suivant inclut certaines erreurs courantes et leurs causes.

  • ERROR_BAD_LENGTH

    Le membre BufferSize du membre Wnode de Properties spécifie une taille incorrecte.

  • 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.
    • Le membre LogFileNameOffset de Properties n’est pas valide.
    • Le membre LoggerNameOffset de Properties n’est pas valide.

    Windows Server 2003 et Windows XP : Le membre GUID de la structure Wnode est SystemTraceControlGuid, mais le paramètre InstanceName n’est pas KERNEL_LOGGER_NAME.

  • ERROR_ACCESS_DENIED

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

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

Remarques

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

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

Lors de l’entrée, les membres doivent spécifier les nouvelles valeurs pour les propriétés à mettre à jour. Vous pouvez mettre à jour les propriétés suivantes.

  • EnableFlags : définissez ce membre sur 0 pour désactiver tous les fournisseurs de noyau. Sinon, vous devez spécifier les fournisseurs de noyau que vous souhaitez activer ou conserver activés. S’applique uniquement aux sessions d’enregistreur d’événements système.

  • FlushTimer : définissez ce membre si vous souhaitez modifier le délai d’attente avant de vider les mémoires tampons. Si ce membre a la valeur 0, le membre n’est pas mis à jour.

  • LogFileNameOffset : définissez ce membre si vous souhaitez basculer vers un autre fichier journal. Si ce membre est 0, le nom de fichier n’est pas mis à jour. Si le décalage n’est pas égal à zéro et que vous ne modifiez pas le nom du fichier journal, la fonction retourne une erreur.

  • LogFileMode : définissez ce membre si vous souhaitez activer et désactiver EVENT_TRACE_REAL_TIME_MODE . Pour désactiver le temps réel, définissez ce membre sur 0. Pour activer le temps réel, définissez ce membre sur EVENT_TRACE_REAL_TIME_MODE et il sera OR’d avec les modes actuels.

  • MaximumBuffers : définissez ce membre si vous souhaitez modifier le nombre maximal de mémoires tampons qu’ETW utilise. Si ce membre a la valeur 0, le membre n’est pas mis à jour.

Pour les sessions d’enregistreur d’événements privées, vous pouvez uniquement mettre à jour LogFileNameOffset et FlushTimer.

Si vous utilisez une structure de EVENT_TRACE_PROPERTIES nouvellement initialisée, les seuls membres que vous devez spécifier, autres que les membres que vous mettez à jour, sont Wnode.BufferSize, Wnode.Guid et Wnode.Flags.

Si vous utilisez la structure de propriété que vous avez passée à StartTrace, assurez-vous que le membre LogFileNameOffset est 0, sauf si vous modifiez le nom du fichier journal.

Si vous appelez la fonction ControlTrace pour interroger les propriétés de session actuelles, puis mettez à jour ces propriétés pour mettre à jour la session, veillez à définir LogFileNameOffset sur 0 (sauf si vous modifiez le nom du fichier journal) et définissez EVENT_TRACE_PROPERTIES. Wnode.Flags à WNODE_FLAG_TRACED_GUID.

Pour obtenir les paramètres de propriété et les statistiques de session d’une session de suivi d’événements, appelez la fonction ControlTrace .

Exemples

Pour obtenir un exemple qui utilise UpdateTrace, consultez Mise à jour d’une session de suivi d’événements.

Notes

L’en-tête evntrace.h définit UpdateTrace en tant qu’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. La combinaison 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 uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

ControlTrace