Fonction TraceEventInstance (evntrace.h)

Article
08/23/2023

Un fournisseur d’événements basé sur RegisterTraceGuids (« Classique ») utilise la fonction TraceEventInstance pour envoyer un événement structuré à une session de suivi d’événements avec un identificateur instance.

L’événement utilise un identificateur de instance pour associer l’événement à une transaction. Cette fonction peut également être utilisée pour suivre les relations hiérarchiques entre les événements associés.

Syntaxe

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Paramètres

[in] TraceHandle

Gérez la session de suivi d’événements qui enregistre l’événement instance. Le fournisseur obtient le handle lorsqu’il appelle la fonction GetTraceLoggerHandle dans son implémentation ControlCallback .

[in] EventTrace

Pointeur vers une structure EVENT_INSTANCE_HEADER . Les données spécifiques à l’événement sont éventuellement ajoutées à la structure. Le plus grand événement que vous pouvez enregistrer est de 64 Ko. Vous devez spécifier des valeurs pour les membres suivants de la structure EVENT_INSTANCE_HEADER .

Taille
Indicateurs
RegHandle

Selon la complexité des informations fournies par votre fournisseur, vous devez également envisager de spécifier des valeurs pour les membres suivants.

Class.Type
Class.Level

Pour suivre les relations hiérarchiques entre les événements associés, définissez également le membre ParentRegHandle .

[in] InstInfo

Pointeur vers une structure EVENT_INSTANCE_INFO, qui contient le handle d’inscription pour cette classe de trace d’événements et l’identificateur de instance. Utilisez la fonction CreateTraceInstanceId pour initialiser la structure.

[in] ParentInstInfo

Pointeur vers une structure EVENT_INSTANCE_INFO, qui contient le handle d’inscription pour la classe de trace d’événement parente et son identificateur de instance. Utilisez la fonction CreateTraceInstanceId pour initialiser la structure. Définissez sur NULL si vous ne suivez pas une relation hiérarchique.

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_FLAGS

Le membre Flags du EVENT_INSTANCE_HEADER ne contient pas de WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

La mémoire était insuffisante pour terminer l’appel de fonction. Les causes de ce code d’erreur sont décrites dans la section Remarques suivante.
ERROR_INVALID_PARAMETER

Une des conditions suivantes est vraie :
- EventTrace a la valeur NULL.
- pInstInfo a la valeur NULL.
- Les membres de pInstInfo sont NULL.
- TraceHandle a la valeur NULL.
- Le membre Size du EVENT_INSTANCE_HEADER est incorrect.
ERROR_INVALID_HANDLE

TraceHandle n’est pas valide ou spécifie le handle de session de l’enregistreur d’événements du noyau NT.
ERROR_NOT_ENOUGH_MEMORY

La session est à court de mémoire tampon sur laquelle écrire. Cela peut se produire en cas de taux élevé d'événements parce que le sous-système du disque est surchargé ou le nombre de mémoires tampon est trop petit. Au lieu de bloquer jusqu’à ce que davantage de mémoires tampons soient disponibles, TraceEvent ignore l’événement.

Windows 2000 et Windows XP : Non pris en charge.
ERROR_OUTOFMEMORY

L’événement est ignoré car, bien que le pool de mémoires tampons n’ait pas atteint sa taille maximale, la mémoire disponible est insuffisante pour allouer une mémoire tampon supplémentaire et aucune mémoire tampon n’est disponible pour recevoir l’événement.
ERROR_MORE_DATA

Les données d’un événement unique ne peuvent pas s’étendre sur plusieurs mémoires tampons. Un événement de trace est limité à la taille de la mémoire tampon de la session de suivi d’événements moins la taille de la structure EVENT_INSTANCE_HEADER .

Notes

Les fournisseurs ETW basés sur MOF appellent cette fonction.

Notes

La plupart des développeurs n’appellent pas cette fonction. Cette API prend en charge l’ETW basé sur MOF, mais l’ETW basé sur MOF est déconseillé en faveur de l’ETW basé sur le manifeste. En outre, la plupart des fournisseurs MOF utilisent des fonctions wrapper générées par MC.exe au lieu d’appeler directement les API ETW.

Avant que le fournisseur puisse appeler cette fonction, le fournisseur

Doit appeler la fonction RegisterTraceGuids pour s’inscrire elle-même et la classe de trace d’événements.
Vous devez appeler la fonction CreateTraceInstanceId pour créer un identificateur instance pour la classe de trace d’événement inscrite.
Doit être activé. Un contrôleur appelle la fonction EnableTrace pour activer un fournisseur.

L’événement est écrit dans un fichier journal, envoyé aux consommateurs de trace d’événements en temps réel, ou les deux. Le membre LogFileMode de la structure EVENT_TRACE_PROPERTIES passée à StartTrace définit l’emplacement d’envoi de l’événement.

Les événements de trace sont écrits dans l’ordre dans lequel ils se produisent.

Pour suivre des événements non liés, utilisez la fonction TraceEvent .

Windows XP : Ne fonctionne pas correctement.

Exemples

Pour obtenir un exemple de génération d’ensembles d’événements connexes à l’aide de CreateTraceInstanceId et TraceEventInstance, consultez Tracing Event Instances.

Spécifications


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