EvtFormatMessage, fonction (winevt.h)

Article
08/27/2023

Formate une chaîne de message.

Syntaxe

BOOL EvtFormatMessage(
  [in]  EVT_HANDLE   PublisherMetadata,
  [in]  EVT_HANDLE   Event,
  [in]  DWORD        MessageId,
  [in]  DWORD        ValueCount,
  [in]  PEVT_VARIANT Values,
  [in]  DWORD        Flags,
  [in]  DWORD        BufferSize,
  [in]  LPWSTR       Buffer,
  [out] PDWORD       BufferUsed
);

Paramètres

[in] PublisherMetadata

Handle pour les métadonnées du fournisseur que la fonction EvtOpenPublisherMetadata retourne. Le handle agit comme un contexte de mise en forme pour l’identificateur d’événement ou de message.

Vous pouvez définir ce paramètre sur NULL si le service Collecteur d’événements Windows a transféré l’événement. Les événements transférés incluent une section RenderingInfo qui contient les chaînes de message rendues. Vous pouvez également définir ce paramètre sur NULL si la propriété d’événement que vous mettez en forme est définie dans le fichier Winmeta.xml (par exemple, si level est défini sur win :Error). Dans ce dernier cas, le service utilise le fournisseur Winmeta comme contexte de mise en forme et met en forme uniquement les chaînes de message que vous référencez dans votre événement et définies dans le fichier Winmeta.xml.

[in] Event

Handle pour un événement. Le paramètre Flags spécifie la chaîne de message dans l’événement que vous souhaitez mettre en forme. Ce paramètre doit être NULL si le paramètre Flags est défini sur EvtFormatMessageId.

[in] MessageId

Identificateur de ressource de la chaîne de message que vous souhaitez mettre en forme. Pour obtenir l’identificateur de ressource d’une chaîne de message, appelez la fonction GetPublisherMetadataProperty . Définissez ce paramètre uniquement si le paramètre Flags a la valeur EvtFormatMessageId.

[in] ValueCount

Nombre de valeurs dans le paramètre Values .

[in] Values

Tableau de valeurs d’insertion à utiliser lors de la mise en forme de la chaîne de message de l’événement. En règle générale, vous définissez ce paramètre sur NULL et la fonction obtient les valeurs d’insertion à partir des données d’événement elles-mêmes. Vous utilisez ce paramètre pour remplacer le comportement par défaut et fournir les valeurs d’insertion à utiliser. Par exemple, vous pouvez utiliser ce paramètre si vous souhaitez résoudre un SID en nom principal avant d’insérer la valeur.

Pour remplacer les valeurs d’insertion, le paramètre Flags doit être défini sur EvtFormatMessageEvent, EvtFormatMessageXML ou EvtFormatMessageId. Si Flags est défini sur EvtFormatMessageId, l’identificateur de ressource doit identifier la chaîne de message de l’événement.

[in] Flags

Indicateur qui spécifie la chaîne de message dans l’événement à mettre en forme. Pour connaître les valeurs possibles, consultez l’énumération EVT_FORMAT_MESSAGE_FLAGS .

[in] BufferSize

Taille de la mémoire tampon , en caractères.

[in] Buffer

Mémoire tampon allouée à l’appelant qui recevra la chaîne de message mise en forme. Vous pouvez définir ce paramètre sur NULL pour déterminer la taille de mémoire tampon requise.

[out] BufferUsed

Taille, en caractères de la mémoire tampon allouée à l’appelant utilisée par la fonction ou taille de mémoire tampon requise si la fonction échoue avec ERROR_INSUFFICIENT_BUFFER.

Valeur retournée

Code/valeur de retour	Description
TRUE	La fonction a réussi.
FALSE	Échec de la fonction. Appelez la fonction GetLastError pour obtenir le code d’erreur.

Remarques

Lorsque le service tente de trouver un message pour un événement, il recherche dans les ressources de table de messages de l’éditeur indiquées par le paramètre PublisherMetadata . Une fois l’ID de message trouvé, les algorithmes de recherche suivants sont utilisés.

Pour les messages d’événement :

Recherchez le fichier spécifié dans l’attribut messageFileName de l’élément provider .
S’il est introuvable, recherchez les messages système.

Pour les attributs Level, Opcode et Keyword de l’élément d’événement :

Recherchez les ressources du fournisseur Winmeta.
Recherchez le fichier spécifié dans l’attribut messageFileName de l’élément provider .

Pour l’attribut Task de l’élément d’événement :

Recherchez le fichier spécifié dans l’attribut messageFileName de l’élément provider .
Si elle est introuvable, recherchez les ressources du fournisseur Winmeta.

Pour les paramètres localisables référencés sous la forme %%n (où n est l’ID de message) dans le message d’événement :

Recherchez les fichiers répertoriés dans l’attribut parameterFileName de l’élément provider de gauche à droite.
S’il est introuvable, recherchez les messages système.

Exemples

Pour obtenir un exemple montrant comment utiliser cette fonction, consultez Mise en forme des messages d’événement et Obtention des métadonnées d’un fournisseur.

Configuration requise

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

Voir aussi

FormatMessage

Partager via