Fonction TraceMessageVa (evntrace.h)
Un fournisseur d’événements basé sur RegisterTraceGuids (« Classique ») utilise la fonction TraceMessageVa pour envoyer un événement basé sur un message (WPP basé sur TMF) à une session de suivi d’événements à l’aide de paramètres va_list.
Syntaxe
ULONG TraceMessageVa(
[in] TRACEHANDLE LoggerHandle,
[in] ULONG MessageFlags,
[in] LPCGUID MessageGuid,
[in] USHORT MessageNumber,
[in] va_list MessageArgList
);
Paramètres
[in] LoggerHandle
Gérez la session de suivi d’événements qui enregistre l’événement. Le fournisseur obtient le handle lorsqu’il appelle la fonction GetTraceLoggerHandle dans son implémentation ControlCallback .
[in] MessageFlags
Ajoute des informations supplémentaires au début de la section de données spécifique au fournisseur de l’événement. La section de données spécifique au fournisseur de l’événement contient uniquement des données pour les indicateurs définis. La liste variable de données d’arguments suit ces informations. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
TRACE_MESSAGE_GUID : incluez le GUID de la classe de trace d’événements dans le message. Le paramètre MessageGuid contient le GUID de la classe de trace d’événements.
TRACE_MESSAGE_SEQUENCE : incluez un numéro de séquence dans le message. Le numéro de séquence commence à un. Pour utiliser cet indicateur, le contrôleur doit avoir défini le mode EVENT_TRACE_USE_GLOBAL_SEQUENCE ou EVENT_TRACE_USE_LOCAL_SEQUENCE fichier journal lors de la création de la session.
TRACE_MESSAGE_SYSTEMINFO : incluez l’identificateur de thread et l’identificateur de processus dans le message.
TRACE_MESSAGE_TIMESTAMP : incluez un horodatage dans le message.
Les informations sont incluses dans les données d’événement dans l’ordre suivant :
- Numéro de séquence
- GUID de la classe de trace d’événements
- Horodatage
- Identificateur de thread
- Identificateur de processus
[in] MessageGuid
GUID de classe qui identifie le message de trace d’événement.
[in] MessageNumber
Numéro qui identifie de façon unique chaque occurrence du message. Vous devez définir la valeur spécifiée pour ce paramètre ; la valeur doit être significative pour l’application.
[in] MessageArgList
Liste des arguments de variable à ajouter au message. La liste doit être composée de paires d’arguments, comme suit.
- PVOID : pointeur vers les données d’argument.
- size_t : taille des données d’argument, en octets.
Terminez la liste à l’aide d’une paire d’arguments composée d’un pointeur vers NULL et zéro.
L’appelant doit s’assurer que la somme des tailles des arguments + 72 ne dépasse pas la taille de la mémoire tampon de la session de suivi d’é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_INVALID_HANDLE
Le LoggerHandle a la valeur NULL 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, TraceMessage 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_INVALID_PARAMETER
MessageFlags contient une valeur qui n’est pas valide.
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_TRACE_HEADER .
Notes
Les fournisseurs WPP basés sur TMF appellent cette fonction.
Notes
La plupart des développeurs n’appellent pas cette fonction directement. Les fournisseurs WPP utilisent des fonctions wrapper générées par tracewpp.exe au lieu d’appeler des API ETW.
Si vous n’avez pas besoin d’accéder à la fonctionnalité de suivi des messages à partir d’une fonction wrapper, vous pouvez appeler la version TraceMessage de cette fonction.
Les consommateurs devront utiliser le rappel EventCallback pour recevoir et traiter les événements si le paramètre MessageFlags ne contient pas l’indicateur TRACE_MESSAGE_GUID. Si vous ne spécifiez pas l’indicateur TRACE_MESSAGE_GUID, le consommateur ne pourra pas utiliser EventClassCallback , car le membre Header.Guid de la structure EVENT_TRACE ne contiendra pas le GUID de la classe de trace d’événements.
Notez que les membres des structures EVENT_TRACE et EVENT_TRACE_HEADER qui correspondent aux indicateurs MessageFlags sont définis uniquement si l’indicateur correspondant est spécifié. Par exemple, les membres ThreadId et ProcessId de EVENT_TRACE_HEADER sont renseignés uniquement si vous spécifiez l’indicateur TRACE_MESSAGE_SYSTEMINFO.
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | evntrace.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |