Fonction TraceMessage (evntrace.h)
Un fournisseur d’événements basé sur RegisterTraceGuids (« Classique ») utilise la fonction TraceMessage pour envoyer un événement basé sur un message (WPP basé sur TMF) à une session de suivi d’événements.
Syntaxe
ULONG TraceMessage(
[in] TRACEHANDLE LoggerHandle,
[in] ULONG MessageFlags,
[in] LPCGUID MessageGuid,
[in] USHORT MessageNumber,
...
);
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_COMPONENTID
Incluez l’identificateur du composant dans le message. Le paramètre MessageGuid contient l’identificateur du composant.
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.
TRACE_MESSAGE_COMPONENTID et TRACE_MESSAGE_GUID s’excluent mutuellement.
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 (ou identificateur de composant)
- Horodatage
- Identificateur de thread
- Identificateur de processus
[in] MessageGuid
GUID de classe ou ID de composant qui identifie le message. Dépend si MessageFlags contient l’indicateur TRACE_MESSAGE_COMPONENTID ou TRACE_MESSAGE_GUID .
[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.
...
Liste des arguments de variable à ajouter au message. Utilisez cette liste pour spécifier vos données d’événement spécifiques au fournisseur. 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. Voici quelques 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 devez accéder à la fonctionnalité de suivi des messages à partir d’une fonction wrapper, appelez la version TraceMessageVa 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 | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | evntrace.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |