FormatMessageA, fonction (winbase.h)
Formate une chaîne de message. La fonction nécessite une définition de message comme entrée. La définition du message peut provenir d’une mémoire tampon passée dans la fonction . Il peut provenir d’une ressource de table de messages dans un module déjà chargé. Ou l’appelant peut demander à la fonction de rechercher la définition de message dans la ou les ressources de table de messages du système. La fonction recherche la définition de message dans une ressource de table de messages en fonction d’un identificateur de message et d’un identificateur de langue. La fonction copie le texte du message mis en forme dans une mémoire tampon de sortie, en traitant toutes les séquences d’insertion incorporées si nécessaire.
Syntaxe
DWORD FormatMessageA(
[in] DWORD dwFlags,
[in, optional] LPCVOID lpSource,
[in] DWORD dwMessageId,
[in] DWORD dwLanguageId,
[out] LPSTR lpBuffer,
[in] DWORD nSize,
[in, optional] va_list *Arguments
);
Paramètres
[in] dwFlags
Les options de mise en forme et comment interpréter le paramètre lpSource . L’octet d’ordre inférieur de dwFlags spécifie comment la fonction gère les sauts de ligne dans la mémoire tampon de sortie. L’octet d’ordre inférieur peut également spécifier la largeur maximale d’une ligne de sortie mise en forme.
Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
La fonction alloue une mémoire tampon suffisamment grande pour contenir le message mis en forme et place un pointeur vers la mémoire tampon allouée à l’adresse spécifiée par lpBuffer. Le paramètre lpBuffer est un pointeur vers un LPTSTR ; vous devez convertir le pointeur en LPTSTR (par exemple, (LPTSTR)&lpBuffer). Le paramètre nSize spécifie le nombre minimal de TCHAR à allouer pour une mémoire tampon de messages de sortie. L’appelant doit utiliser la fonction LocalFree pour libérer la mémoire tampon quand elle n’est plus nécessaire.
Si la longueur du message mis en forme dépasse 128 000 octets, FormatMessage échoue et un appel ultérieur à GetLastError retourne ERROR_MORE_DATA. Dans les versions précédentes de Windows, cette valeur n’était pas disponible pour être utilisée lors de la compilation d’applications du Windows Store. À partir de Windows 10 cette valeur peut être utilisée. Windows Server 2003 et Windows XP : Si la longueur du message mis en forme dépasse 128 000 octets, FormatMessage n’échoue pas automatiquement avec une erreur de ERROR_MORE_DATA. |
|
Le paramètre Arguments n’est pas une structure va_list , mais un pointeur vers un tableau de valeurs qui représentent les arguments.
Cet indicateur ne peut pas être utilisé avec des valeurs entières 64 bits. Si vous utilisez un entier 64 bits, vous devez utiliser la structure va_list . |
|
Le paramètre lpSource est un handle de module contenant la ou les ressources de table message à rechercher. Si ce handle lpSource a la valeur NULL, le fichier image d’application du processus actuel est recherché. Cet indicateur ne peut pas être utilisé avec FORMAT_MESSAGE_FROM_STRING.
Si le module n’a pas de ressource de table de messages, la fonction échoue avec ERROR_RESOURCE_TYPE_NOT_FOUND. |
|
Le paramètre lpSource est un pointeur vers une chaîne terminée par null qui contient une définition de message. La définition de message peut contenir des séquences d’insertion, tout comme le texte du message dans une ressource de table de messages. Cet indicateur ne peut pas être utilisé avec FORMAT_MESSAGE_FROM_HMODULE ou FORMAT_MESSAGE_FROM_SYSTEM. |
|
La fonction doit rechercher le message demandé dans la ou les ressources de table de message système. Si cet indicateur est spécifié avec FORMAT_MESSAGE_FROM_HMODULE, la fonction recherche dans la table des messages système si le message est introuvable dans le module spécifié par lpSource. Cet indicateur ne peut pas être utilisé avec FORMAT_MESSAGE_FROM_STRING.
Si cet indicateur est spécifié, une application peut transmettre le résultat de la fonction GetLastError pour récupérer le texte du message pour une erreur définie par le système. |
|
Les séquences d’insertion dans la définition de message telles que %1 doivent être ignorées et passées à la mémoire tampon de sortie inchangée. Cet indicateur est utile pour extraire un message en vue d’une mise en forme ultérieure. Si cet indicateur est défini, le paramètre Arguments est ignoré. |
L’octet d’ordre inférieur de dwFlags peut spécifier la largeur maximale d’une ligne de sortie mise en forme. Voici les valeurs possibles de l’octet de bas ordre.
Si l’octet d’ordre inférieur est une valeur différente de zéro autre que FORMAT_MESSAGE_MAX_WIDTH_MASK, il spécifie le nombre maximal de caractères dans une ligne de sortie. La fonction ignore les sauts de ligne réguliers dans le texte de définition du message. La fonction ne fractionne jamais une chaîne délimitée par des espaces blancs sur un saut de ligne. La fonction stocke les sauts de ligne codés en dur dans le texte de définition du message dans la mémoire tampon de sortie. Les sauts de ligne codés en dur sont codés avec la séquence d’échappement %n.
[in, optional] lpSource
Emplacement de la définition de message. Le type de ce paramètre dépend des paramètres du paramètre dwFlags .
Si aucun de ces indicateurs n’est défini dans dwFlags, lpSource est ignoré.
[in] dwMessageId
Identificateur de message pour le message demandé. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING.
[in] dwLanguageId
Identificateur de langue pour le message demandé. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING.
Si vous transmettez un LANGID spécifique dans ce paramètre, FormatMessage retourne un message pour ce LANGID uniquement. Si la fonction ne trouve pas de message pour ce LANGID, elle définit Last-Error sur ERROR_RESOURCE_LANG_NOT_FOUND. Si vous transmettez zéro, FormatMessage recherche un message pour les LANGID dans l’ordre suivant :
- Langue neutre
- LANGID du thread, en fonction de la valeur des paramètres régionaux du thread
- LANGID par défaut de l’utilisateur, en fonction de la valeur des paramètres régionaux par défaut de l’utilisateur
- LANGID par défaut du système, basé sur la valeur des paramètres régionaux par défaut du système
- Français
[out] lpBuffer
Pointeur vers une mémoire tampon qui reçoit la chaîne terminée par null qui spécifie le message mis en forme. Si dwFlags inclut FORMAT_MESSAGE_ALLOCATE_BUFFER, la fonction alloue une mémoire tampon à l’aide de la fonction LocalAlloc et place le pointeur vers la mémoire tampon à l’adresse spécifiée dans lpBuffer.
Cette mémoire tampon ne peut pas dépasser 64 000 octets.
[in] nSize
Si l’indicateur FORMAT_MESSAGE_ALLOCATE_BUFFER n’est pas défini, ce paramètre spécifie la taille de la mémoire tampon de sortie, dans les TCHAR. Si FORMAT_MESSAGE_ALLOCATE_BUFFER est défini, ce paramètre spécifie le nombre minimal de TCHAR à allouer pour une mémoire tampon de sortie.
La mémoire tampon de sortie ne peut pas dépasser 64 000 octets.
[in, optional] Arguments
Tableau de valeurs utilisées comme insertion de valeurs dans le message mis en forme. Un %1 dans la chaîne de format indique la première valeur du tableau Arguments ; %2 indique le deuxième argument ; et ainsi de suite.
L’interprétation de chaque valeur dépend des informations de mise en forme associées à l’insertion dans la définition du message. La valeur par défaut consiste à traiter chaque valeur comme un pointeur vers une chaîne terminée par null.
Par défaut, le paramètre Arguments est de type va_list*, qui est un type de données spécifique au langage et à l’implémentation pour décrire un nombre variable d’arguments. L’état de l’argument va_list n’est pas défini lors du retour de la fonction. Pour réutiliser le va_list , détruisez le pointeur de liste d’arguments variables à l’aide de va_end et réinitialisez-le avec va_start.
Si vous n’avez pas de pointeur de type va_list*, spécifiez l’indicateur FORMAT_MESSAGE_ARGUMENT_ARRAY et transmettez un pointeur vers un tableau de valeurs DWORD_PTR ; ces valeurs sont entrées dans le message mis en forme en tant que valeurs d’insertion. Chaque insertion doit avoir un élément correspondant dans le tableau.
Valeur retournée
Si la fonction réussit, la valeur de retour est le nombre de TCHAR stockés dans la mémoire tampon de sortie, à l’exclusion du caractère null de fin.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Dans le texte du message, plusieurs séquences d’échappement sont prises en charge pour la mise en forme dynamique du message. Ces séquences d’échappement et leurs significations sont indiquées dans les tableaux suivants. Toutes les séquences d’échappement commencent par le caractère pourcentage (%).
| Séquence d'échappement | Signification |
|---|---|
| %0 | Termine une ligne de texte de message sans nouveau caractère de ligne de fin. Cette séquence d’échappement peut être utilisée pour créer de longues lignes ou pour terminer le message lui-même sans nouveau caractère de ligne à la fin. Il est utile pour les messages d’invite. |
| %n ! chaîne de format ! |
Identifie une séquence d’insertion. La valeur de n peut se trouver dans la plage comprise entre 1 et 99. La chaîne de format (qui doit être entourée de marques d’exclamation) est facultative et la valeur par défaut est !s ! si l’option n’est pas spécifiée. Pour plus d’informations, consultez Mettre en forme les champs de spécification.
La chaîne de format peut inclure un spécificateur de largeur et de précision pour les chaînes et un spécificateur de largeur pour les entiers. Utilisez un astérisque () pour spécifier la largeur et la précision. Par exemple, %1 !. *s ! ou %1 !*u !. Si vous n’utilisez pas les spécificateurs de largeur et de précision, les nombres d’insertion correspondent directement aux arguments d’entrée. Par exemple, si la chaîne source est « %1 %2 %1 » et que les arguments d’entrée sont « Bill » et « Bob », la chaîne de sortie mise en forme est « Bill Bob Bill ». Toutefois, si vous utilisez un spécificateur de largeur et de précision, les nombres d’insertion ne correspondent pas directement aux arguments d’entrée. Par exemple, les numéros d’insertion de l’exemple précédent peuvent passer à « %1 !*.*s ! %4 %5 !*s ! » Les nombres d’insertion varient selon que vous utilisez un tableau d’arguments (FORMAT_MESSAGE_ARGUMENT_ARRAY) ou un va_list. Pour un tableau d’arguments, le numéro d’insertion suivant est n+2 si la chaîne de format précédente contenait un astérisque et est n+3 si deux astérisque ont été spécifiés. Pour un va_list, le numéro d’insertion suivant est n+1 si la chaîne de format précédente contenait un astérisque et est n+2 si deux astérisque ont été spécifiés. Si vous souhaitez répéter « Facture », comme dans l’exemple précédent, les arguments doivent inclure « Facture » deux fois. Par exemple, si la chaîne source est « %1 !*.*s ! %4 %5 !*s ! », les arguments peuvent être, 4, 2, Bill, Bob, 6, Bill (si vous utilisez l’indicateur FORMAT_MESSAGE_ARGUMENT_ARRAY ). La chaîne mise en forme serait alors « Bi Bob Bill ». La répétition de nombres d’insertion lorsque la chaîne source contient des spécificateurs de largeur et de précision peut ne pas produire les résultats prévus. Si vous remplacez %5 par %1, la fonction essaie d’imprimer une chaîne à l’adresse 6 (entraînant probablement une violation d’accès). Les spécificateurs de format à virgule flottante (e, E, f et g) ne sont pas pris en charge. La solution de contournement consiste à utiliser la fonction StringCchPrintf pour mettre en forme le nombre à virgule flottante dans une mémoire tampon temporaire, puis à utiliser cette mémoire tampon comme chaîne d’insertion. Les insertions qui utilisent le préfixe I64 sont traitées comme deux arguments 32 bits. Ils doivent être utilisés avant d’utiliser les arguments suivants. Notez qu’il peut être plus facile pour vous d’utiliser StringCchPrintf au lieu de ce préfixe. |
Tout autre caractère nondigit suivant un caractère de pourcentage est mis en forme dans le message de sortie sans le caractère de pourcentage. Voici quelques exemples.
| Chaîne de format | Sortie résultante |
|---|---|
| %% | Un signe de pourcentage unique. |
| %Espace | Un espace unique. Cette chaîne de format peut être utilisée pour garantir le nombre approprié d’espaces de fin dans une ligne de texte de message. |
| %. | Un point unique. Cette chaîne de format peut être utilisée pour inclure un point unique au début d’une ligne sans mettre fin à la définition du texte du message. |
| %! | Point d’exclamation unique. Cette chaîne de format peut être utilisée pour inclure un point d’exclamation immédiatement après une insertion sans qu’il soit confondu avec le début d’une chaîne de format. |
| %n | Saut de ligne dure lorsque la chaîne de format se produit à la fin d’une ligne. Cette chaîne de format est utile lorsque FormatMessage fournit des sauts de ligne régulières afin que le message s’adapte à une certaine largeur. |
| %r | Retour chariot dur sans caractère de nouvelle ligne de fin. |
| %t | Un seul onglet. |
Remarques sur la sécurité
Si cette fonction est appelée sans FORMAT_MESSAGE_IGNORE_INSERTS, le paramètre Arguments doit contenir suffisamment de paramètres pour satisfaire toutes les séquences d’insertion dans la chaîne de message, et ils doivent être du type correct. Par conséquent, n’utilisez pas de chaînes de message non approuvées ou inconnues avec des insertions activées, car elles peuvent contenir plus de séquences d’insertion que celles d’Arguments , ou celles qui peuvent être de type incorrect. En particulier, il est dangereux de prendre un code d’erreur système arbitraire retourné à partir d’une API et d’utiliser FORMAT_MESSAGE_FROM_SYSTEM sans FORMAT_MESSAGE_IGNORE_INSERTS.Exemples
La fonction FormatMessage peut être utilisée pour obtenir des chaînes de message d’erreur pour les codes d’erreur système retournés par GetLastError. Pour obtenir un exemple, consultez Récupération du code Last-Error.
L’exemple suivant montre comment utiliser un tableau d’arguments et les spécificateurs de largeur et de précision.#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
void main(void)
{
LPWSTR pMessage = L"%1!*.*s! %4 %5!*s!";
DWORD_PTR pArgs[] = { (DWORD_PTR)4, (DWORD_PTR)2, (DWORD_PTR)L"Bill", // %1!*.*s! refers back to the first insertion string in pMessage
(DWORD_PTR)L"Bob", // %4 refers back to the second insertion string in pMessage
(DWORD_PTR)6, (DWORD_PTR)L"Bill" }; // %5!*s! refers back to the third insertion string in pMessage
const DWORD size = 100+1;
WCHAR buffer[size];
if (!FormatMessage(FORMAT_MESSAGE_FROM_STRING | FORMAT_MESSAGE_ARGUMENT_ARRAY,
pMessage,
0,
0,
buffer,
size,
(va_list*)pArgs))
{
wprintf(L"Format message failed with 0x%x\n", GetLastError());
return;
}
// Buffer contains " Bi Bob Bill".
wprintf(L"Formatted message: %s\n", buffer);
}
L’exemple suivant montre comment implémenter l’exemple précédent à l’aide de va_list.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
LPWSTR GetFormattedMessage(LPWSTR pMessage, ...);
void main(void)
{
LPWSTR pBuffer = NULL;
LPWSTR pMessage = L"%1!*.*s! %3 %4!*s!";
// The variable length arguments correspond directly to the format
// strings in pMessage.
pBuffer = GetFormattedMessage(pMessage, 4, 2, L"Bill", L"Bob", 6, L"Bill");
if (pBuffer)
{
// Buffer contains " Bi Bob Bill".
wprintf(L"Formatted message: %s\n", pBuffer);
LocalFree(pBuffer);
}
else
{
wprintf(L"Format message failed with 0x%x\n", GetLastError());
}
}
// Formats a message string using the specified message and variable
// list of arguments.
LPWSTR GetFormattedMessage(LPWSTR pMessage, ...)
{
LPWSTR pBuffer = NULL;
va_list args = NULL;
va_start(args, pMessage);
FormatMessage(FORMAT_MESSAGE_FROM_STRING |
FORMAT_MESSAGE_ALLOCATE_BUFFER,
pMessage,
0,
0,
(LPWSTR)&pBuffer,
0,
&args);
va_end(args);
return pBuffer;
}
Notes
L’en-tête winbase.h définit FormatMessage comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 | winbase.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
Fonctions de gestion des erreurs
Tables de messages