Fonction EnableTrace (evntrace.h)

Un contrôleur de session de suivi appelle EnableTrace pour configurer la façon dont un fournisseur d’événements ETW consigne les événements dans une session de suivi.

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

Syntaxe

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

Paramètres

[in] Enable

Définissez la valeur 1 pour activer la réception des événements du fournisseur ou pour ajuster les paramètres utilisés lors de la réception des événements du fournisseur (par exemple, pour modifier le niveau et les mots clés). Définissez sur 0 pour désactiver la réception des événements du fournisseur.

[in] EnableFlag

Masque de bits 32 bits de mots clés qui déterminent les catégories d’événements que vous souhaitez que le fournisseur écrive. Le fournisseur écrit généralement un événement si les bits mot clé de l’événement correspondent à l’un des bits définis dans cette valeur ou si l’événement n’a pas de mot clé bits définis, en plus de répondre aux critères EnableLevel.

Notes

Les fournisseurs basés sur EventRegister prennent en charge les mots clés 64 bits. Utilisez EnableTraceEx2 pour activer les fournisseurs à l’aide d’un masque MatchAnyKeyword 64 bits.

[in] EnableLevel

Valeur qui indique le niveau maximal d’événements que vous souhaitez que le fournisseur écrive. Le fournisseur écrit généralement un événement si le niveau de l’événement est inférieur ou égal à cette valeur, en plus de répondre aux critères EnableFlag .

Cette valeur doit être comprise entre 1 et 255. Microsoft définit la sémantique des niveaux 1 à 5, comme indiqué ci-dessous. Les valeurs inférieures indiquent des événements plus graves. Chaque valeur d’EnableLevel active le niveau spécifié et tous les niveaux plus sévères. Par exemple, si vous spécifiez TRACE_LEVEL_WARNING, votre consommateur recevra des événements d’avertissement, d’erreur et critiques.

Valeur	Signification
TRACE_LEVEL_CRITICAL (1)	Événements de sortie ou d’arrêt anormaux
TRACE_LEVEL_ERROR (2)	Événements d’erreur grave
TRACE_LEVEL_WARNING (3)	Événements d’avertissement tels que les échecs d’allocation
TRACE_LEVEL_INFORMATION (4)	Événements d’information sans erreur
TRACE_LEVEL_VERBOSE (5)	Événements de diagnostic détaillés

Les TRACE_LEVEL constantes sont définies dans evntrace.h. Les constantes équivalentes WINMETA_LEVEL sont définies dans winmeta.h.

[in] ControlGuid

GUID de contrôle (ID de fournisseur) du fournisseur d’événements que vous souhaitez activer ou désactiver.

[in] TraceHandle

Handle de la session de suivi d’événements pour laquelle vous configurez le fournisseur. La fonction StartTrace retourne ce handle lorsqu’une nouvelle trace est démarrée. Pour obtenir le handle d’une trace existante, utilisez ControlTrace pour interroger les propriétés de trace en fonction du nom de la trace, puis obtenir le handle à partir du champ Wnode.HistoricalContext des données retournées EVENT_TRACE_PROPERTIES .

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_INVALID_PARAMETER

  Une des conditions suivantes est vraie :

  • ControlGuid a la valeur NULL.
  • TraceHandle a la valeur NULL.

• ERROR_INVALID_FUNCTION

  Vous ne pouvez pas modifier les indicateurs d’activation et le niveau lorsque le fournisseur n’est pas inscrit.

• ERROR_WMI_GUID_NOT_FOUND

  Le fournisseur n’est pas inscrit. Se produit lorsque KB307331 ou Windows 2000 Service Pack 4 est installé et que le fournisseur n’est pas inscrit. Pour éviter cette erreur, le fournisseur doit d’abord être inscrit.

• ERROR_NO_SYSTEM_RESOURCES

  Dépassement du nombre de sessions de suivi pouvant activer le fournisseur.

• ERROR_ACCESS_DENIED

  Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du Performance Log Users groupe et les services exécutant LocalSystem, LocalServiceou NetworkService peuvent activer les fournisseurs d’événements dans une session inter-processus. Pour accorder à un utilisateur restreint la possibilité d’activer un fournisseur d’événements, ajoutez-le au Performance Log Users groupe ou consultez EventAccessControl.

  Windows XP et Windows 2000 : Tout le monde peut activer un fournisseur d’événements.

Notes

Les contrôleurs de suivi d’événements appellent cette fonction pour configurer les fournisseurs d’événements qui écrivent des événements dans la session. Par exemple, un contrôleur peut appeler cette fonction pour commencer à collecter des événements à partir d’un fournisseur, pour ajuster le niveau ou les mots clés des événements collectés auprès d’un fournisseur, ou pour arrêter la collecte d’événements à partir d’un fournisseur.

Cette fonction est obsolète. Pour des fonctionnalités supplémentaires, le nouveau code doit utiliser EnableTraceEx2.

Les deux appels de fonction suivants sont équivalents :

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Pour plus d’informations sur la sémantique de la configuration des fournisseurs pour une session, reportez-vous à la documentation d’EnableTraceEx2.

Spécifications

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

StartTrace

EnableTraceEx2