ProcessTrace, fonction (evntrace.h)

La fonction ProcessTrace remet les événements d’une ou de plusieurs sessions de traitement de trace ETW au consommateur.

Syntaxe

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE HandleArray,
  [in] ULONG        HandleCount,
  [in] LPFILETIME   StartTime,
  [in] LPFILETIME   EndTime
);

Paramètres

[in] HandleArray

Pointeur vers un tableau de handles de session de traitement de trace obtenus à partir d’appels antérieurs à la fonction OpenTrace .

Le tableau peut contenir jusqu’à 64 handles pour les sessions de traitement de fichiers ou il peut contenir un handle pour une session de traitement en temps réel. Le tableau ne peut pas contenir à la fois des handles de session de traitement de fichiers et des handles de session de traitement en temps réel.

[in] HandleCount

Nombre d’éléments dans HandleArray.

[in] StartTime

Pointeur vers une structure FILETIME facultative qui spécifie la période de début pour laquelle vous souhaitez recevoir des événements. La fonction ne remet pas d’événements avec des horodatages antérieurs à StartTime.

[in] EndTime

Pointeur vers une structure FILETIME facultative qui spécifie la période de fin pour laquelle vous souhaitez recevoir des événements. La fonction ne remet pas d’événements avec des horodatages après EndTime.

Windows Server 2003 : Cette valeur est ignorée pour la remise d’événements en temps réel.

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

  HandleCount n’est pas valide ou le nombre de handles est supérieur à 64.

• ERROR_INVALID_HANDLE

  Un élément de HandleArray n’est pas un handle de session de suivi d’événements valide.

• ERROR_INVALID_TIME

  EndTime est inférieur à StartTime.

• ERROR_INVALID_PARAMETER

  HandleArray a la valeur NULL, contient à la fois des sessions de traitement de fichiers et des sessions de traitement en temps réel, ou contient plusieurs sessions de traitement en temps réel.

• ERROR_NOACCESS

  Une exception s’est produite dans l’une des fonctions de rappel qui reçoit les événements.

• ERROR_CANCELLED

  Indique que le consommateur a annulé le traitement en retournant FALSE dans sa fonction BufferCallback .

• ERROR_WMI_INSTANCE_NOT_FOUND

  La session de collecte de traces à partir de laquelle vous essayez de consommer des événements en temps réel n’est pas en cours d’exécution ou n’a pas le mode de trace en temps réel activé.

Notes

Les consommateurs de trace appellent cette fonction pour traiter les événements d’une ou plusieurs sessions de traitement des traces. Cette fonction se bloque jusqu’à la fin du traitement.

Avant d’appeler ProcessTrace, utilisez OpenTrace pour ouvrir des handles pour suivre les sessions de traitement.

La fonction ProcessTrace fournit les événements des sessions en appelant les fonctions de rappel BufferCallback, EventCallback et EventRecordCallback du consommateur.

La fonction ProcessTrace tente de remettre les événements dans l’ordre en fonction de l’horodatage de l’événement (c’est-à-dire, elle tente de remettre les événements les plus anciens au plus récents). Dans certains cas, ProcessTrace peut remettre des événements dans le désordre.

• Si l’horloge utilisée pour les horodatages d’événements est ajustée vers l’arrière pendant la collecte des traces, l’ordre de livraison des événements est imprévisible. Pour éviter ce problème, utilisez l’horloge QPC au lieu de l’horloge de temps système lors de la collecte de la trace.
• Si plusieurs événements sont collectés avec le même horodatage sur des processeurs différents, l’ordre de livraison des événements est imprévisible.
• Si un événement a un horodatage non valide (par exemple, en raison d’une corruption de fichier), l’ordre de livraison de cet événement et d’autres événements dans la trace peuvent être imprévisibles.

La fonction ProcessTrace bloque le thread jusqu’à ce qu’il remette tous les événements, que la fonction BufferCallback retourne FALSE ou que vous appelez CloseTrace. En outre, si le consommateur consomme des événements en temps réel, la fonction ProcessTrace retourne une fois que le contrôleur a arrêté la session de trace. (Notez qu’il peut y avoir un délai de plusieurs secondes avant le retour de la fonction.)

Windows Server 2003 : Vous pouvez appeler CloseTrace uniquement après le retour de ProcessTrace .

Exemples

Pour obtenir un exemple qui utilise ProcessTrace, consultez Utilisation de TdhFormatProperty pour consommer des données d’événement.

Spécifications

Voir aussi

BufferCallback

EventCallback

EventRecordCallback

OpenTrace