ProcessTrace, fonction (evntrace.h)

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

Syntaxe

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PROCESSTRACE_HANDLE *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 aux sessions de traitement de fichiers ou contenir un handle vers 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 avant 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 est 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 traitement annulé par le consommateur en retournant FALSE dans sa fonction BufferCallback .

• ERROR_WMI_INSTANCE_NOT_FOUND

  La session de collecte de trace à partir de laquelle vous essayez d’utiliser 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é.

Remarques

Les consommateurs de trace appellent cette fonction pour traiter les événements d’une ou plusieurs sessions de traitement de suivi. Cette fonction se bloque jusqu’à ce que le traitement se termine.

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

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

La fonction ProcessTrace tente de remettre des événements dans l’ordre en fonction de l’horodatage de l’événement (c’est-à-dire, il tente de remettre les événements les plus anciens au plus récent). Dans certains cas, ProcessTrace peut remettre des événements hors de commande.

• Si l’horloge utilisée pour les horodatages d’événements est ajustée vers l’arrière pendant la collecte de 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 différents processeurs, 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 altération de fichier), l’ordre de remise de cet événement et d’autres événements dans la trace peut être imprévisible.

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

Windows Server 2003 : Vous ne pouvez appeler CloseTrace qu’une fois ProcessTrace retourné.

Examples

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