Fonction TdhFormatProperty (tdh.h)

  • Article

Met en forme une valeur de propriété pour l’affichage.

Syntaxe

TDHSTATUS TdhFormatProperty(
  [in]            PTRACE_EVENT_INFO EventInfo,
  [in, optional]  PEVENT_MAP_INFO   MapInfo,
  [in]            ULONG             PointerSize,
  [in]            USHORT            PropertyInType,
  [in]            USHORT            PropertyOutType,
  [in]            USHORT            PropertyLength,
  [in]            USHORT            UserDataLength,
  [in]            PBYTE             UserData,
  [in, out]       PULONG            BufferSize,
  [out, optional] PWCHAR            Buffer,
  [out]           PUSHORT           UserDataConsumed
);

Paramètres

[in] EventInfo

Structure TRACE_EVENT_INFO qui contient les informations d’événement. Pour obtenir cette structure, appelez la fonction TdhGetEventInformation.

[in, optional] MapInfo

Structure EVENT_MAP_INFO qui mappe les valeurs de bits et d’entiers à des chaînes. Pour obtenir cette structure, appelez la fonction TdhGetEventMapInformation. Pour obtenir le nom de la carte, utilisez le membre MapNameOffset de la structure EVENT_PROPERTY_INFO. Si vous ne fournissez pas les informations cartographiques d’une propriété mappée, la fonction met en forme la valeur entière ou bit.

[in] PointerSize

Taille d’une valeur de pointeur dans les données d’événement. Pour obtenir la taille, accédez au EVENT_RECORD. Membre EventHeader.Flags . La taille du pointeur est de 4 octets si l’indicateur EVENT_HEADER_FLAG_32_BIT_HEADER est défini ; sinon, il est de 8 octets si l’indicateur EVENT_HEADER_FLAG_64_BIT_HEADER est défini. La structure EVENT_RECORD (evntcons.h) est passée à votre [fonction de rappel PEVENT_RECORD_CALLBACK].

[in] PropertyInType

Type d’entrée de la propriété. Utilisez le membre InType de la structure EVENT_PROPERTY_INFO pour définir ce paramètre.

[in] PropertyOutType

Type de sortie de la propriété. Utilisez le membre OutType de la structure EVENT_PROPERTY_INFO pour définir ce paramètre.

[in] PropertyLength

Longueur, en octets, de la propriété. Utilisez le membre Length de la structure EVENT_PROPERTY_INFO pour définir ce paramètre.

[in] UserDataLength

Taille, en octets, de la mémoire tampon UserData . Consultez la section Notes.

[in] UserData

Mémoire tampon qui contient les données d’événement. Consultez la section Notes.

[in, out] BufferSize

Taille, en octets, de la mémoire tampon . Si la fonction réussit, ce paramètre reçoit la taille de la mémoire tampon utilisée. Si la mémoire tampon est trop petite, la fonction retourne ERROR_INSUFFICIENT_BUFFER et définit ce paramètre sur la taille de mémoire tampon requise. Si la taille de la mémoire tampon est égale à zéro lors de l’entrée, aucune donnée n’est retournée dans la mémoire tampon et ce paramètre reçoit la taille de mémoire tampon requise.

[out, optional] Buffer

Mémoire tampon allouée à l’appelant qui contient la valeur de la propriété mise en forme. Pour déterminer la taille de mémoire tampon requise, définissez ce paramètre sur NULL et BufferSize sur zéro.

[out] UserDataConsumed

Longueur, en octets, des données d’événement consommées. Utilisez cette valeur pour ajuster les valeurs des paramètres UserData et UserDataLength . Consultez la section Notes.

Valeur de retour

Retourne ERROR_SUCCESS en cas de réussite. Sinon, cette fonction retourne l’un des codes de retour suivants en plus d’autres.

Code de retour Description
ERROR_INSUFFICIENT_BUFFER La taille de la mémoire tampon pBuffer est trop petite. Utilisez la taille de mémoire tampon requise définie dans pBufferSize pour allouer une nouvelle mémoire tampon.
ERROR_INVALID_PARAMETER Un ou plusieurs des paramètres ne sont pas valides.
ERROR_EVT_INVALID_EVENT_DATA Les données d’événement ne correspondent pas à la définition d’événement dans le manifeste.

Remarques

En règle générale, vous appelez cette fonction dans une boucle. Utilisez le TRACE_EVENT_INFO. Membre TopLevelPropertyCount pour contrôler la boucle (la fonction TdhGetEventInformation retourne la structure TRACE_EVENT_INFO). Avant d’entrer la boucle, vous définissez les paramètres UserData et UserDataLength sur la valeur des membres UserData et UserDataLength de la structure EVENT_RECORD, respectivement. La structure EVENT_RECORD est passée à votre [fonction de rappel PEVENT_RECORD_CALLBACK].

Déterminez si la propriété est un tableau. La propriété est un tableau si le EVENT_PROPERTY_INFO. Le membre Flags est défini sur PropertyParamCount ou le membre EVENT_PROPERTY_INFO.count est supérieur à 1. Appelez la fonction TdhFormatProperty dans une boucle en fonction du nombre d’éléments dans le tableau.

Après avoir appelé la fonction TdhFormatProperty , utilisez la valeur du paramètre UserDataConsumed pour définir les nouvelles valeurs des paramètres UserData et UserDataLength (Soustraire UserDataConsumed de UserDataLength et utiliser UserDataLength pour incrémenter le pointeur UserData ).

Si la propriété est une adresse IP V6, vous devez définir le paramètre PropertyLength sur la taille de la structure IN6_ADDR . La propriété est considérée comme une adresse IP V6 si les conditions suivantes sont remplies :

Exemples

Pour obtenir un exemple qui montre comment appeler cette fonction , consultez Utilisation de TdhFormatProperty pour consommer des données d’événement.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible Windows
En-tête tdh.h
Bibliothèque Tdh.lib
DLL Tdh.dll