UpdateTraceW, fonction (evntrace.h)
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 UpdateTraceW(
CONTROLTRACE_ID TraceId,
LPCWSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Paramètres
TraceId
InstanceName
Nom de la session de suivi des é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 structure contiennent les paramètres et les statistiques mis à jour pour la session de suivi des é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 des événements. Pour accorder à un utilisateur restreint la possibilité de contrôler les sessions de suivi, ajoutez-les au groupe Utilisateurs du journal des performances.
Windows XP et Windows 2000 : Tout le monde peut contrôler une session de suivi.
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_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 tampons. Si ce membre est 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 est 0, le membre n’est pas mis à jour.
Pour les sessions d’enregistreur d’événements privés, 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és que vous avez transmise à StartTrace, vérifiez 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 mettre à 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 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 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 |