| Nom |
Description |
| dwFlags |
Ce paramètre contient un ensemble de drapeaux de bits spécifiant les aspects du processus de formatage et comment interpréter le paramètre lpSource.
L'octet de poids faible de dwFlags spécifie comment la fonction gère les sauts de ligne dans le tampon de sortie. L'octet de poids faible peut également spécifier la largeur maximale
d'une ligne de sortie formatée. Vous pouvez spécifier une combinaison des drapeaux de bits suivants : |
| FORMAT_MESSAGE_ALLOCATE_BUFFER |
Cette valeur permet d'indiquer que le paramètre lpBuffer est un pointeur sur un pointeur PVOID et que le paramètre nSize spécifie le nombre minimal d'octets (version ANSI) ou de caractères (version Unicode) à allouer à un tampon de message de sortie. La fonction alloue un tampon suffisamment grand pour contenir le message formaté et place un pointeur sur le tampon alloué à l'adresse spécifiée par lpBuffer. L'appelant doit utiliser la fonction LocalFree pour libérer le tampon lorsqu'il n'est plus nécessaire. |
| FORMAT_MESSAGE_IGNORE_INSERTS |
Cette valeur permet d'indiquer que les séquences d'insertion dans la définition de message doivent être ignorées et transmises au tampon de sortie sans aucune modification. Ce drapeau est utile pour récupérer un message pour un formatage ultérieur. Si ce drapeau est défini, le paramètre Arguments est ignoré. |
| FORMAT_MESSAGE_FROM_STRING |
Cette valeur permet d'indiquer que lpSource est un pointeur sur une définition de message terminée par un zéro. La définition du message peut contenir des séquences d'insertion, tout comme le texte du message dans une ressource de table de messages. Ne peut pas être utilisé avec FORMAT_MESSAGE_FROM_HMODULE ou FORMAT_MESSAGE_FROM_SYSTEM. |
| FORMAT_MESSAGE_FROM_HMODULE |
Cette valeur permet d'indiquer que lpSource est un descripteur de module contenant la ou les ressources de la table de messages à rechercher. Si l'identificateur lpSource est NULL, le fichier image d'application du processus en cours sera recherché. Ne peut pas être utilisé avec FORMAT_MESSAGE_FROM_STRING. |
| FORMAT_MESSAGE_FROM_SYSTEM |
Cette valeur permet d'indiquer que la fonction doit rechercher le message demandé dans la ou les ressources de la table des messages système. Si ce drapeau est spécifié avec
FORMAT_MESSAGE_FROM_HMODULE, la fonction recherche dans la table des messages système si le message n'est pas trouvé dans le module spécifié par lpSource. Ne peut pas être
utilisé avec FORMAT_MESSAGE_FROM_STRING. Si ce drapeau est spécifié, une application peut transmettre le résultat de la fonction GetLastError
pour extraire le texte du message pour une erreur définie par le système. |
| FORMAT_MESSAGE_ARGUMENT_ARRAY |
Cette valeur permet d'indiquer que le paramètre Arguments n'est pas une structure va_list, mais simplement un pointeur sur un tableau de valeurs 32 bits représentant les paramètres. |
| L'octet de poids faible de dwFlags peut spécifier la largeur maximale d'une ligne de sortie formatée. Utilisez la constante FORMAT_MESSAGE_MAX_WIDTH_MASK et les opérations
booléennes au niveau du bit pour définir et récupérer cette valeur de largeur maximale. Le tableau suivant montre comment FormatMessage interprète la valeur de l'octet de poids faible : |
| 0 |
Cette valeur permet d'indiquer qu'il n'y a pas de restrictions de largeur de ligne en sortie. La fonction entrepose les sauts de ligne contenus dans le texte de définition du message dans le tampon de sortie. |
| Une valeur non nulle autre que FORMAT_MESSAGE_MAX_WIDTH_MASK |
La valeur différente de zéro correspond au 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 divise jamais une chaîne de caractères délimitée par un espace blanc en sauts de ligne. La fonction entrepose les sauts de ligne codés en dur dans le texte de définition du message dans
le tampon de sortie. Les sauts de ligne codés en dur sont codés avec la séquence d'échappement %n. |
| FORMAT_MESSAGE_MAX_WIDTH_MASK |
Cette valeur permet d'indiquer que la fonction ignore les sauts de ligne réguliers dans le texte de définition du message. La fonction entrepose les sauts de ligne codés en dur dans le texte de
définition du message dans le tampon de sortie. La fonction ne génère aucun nouveau saut de ligne. |
| lpSource |
Ce paramètre permet d'indiquer l'emplacement de la définition du message. Le type de ce paramètre dépend des paramètres définis dans le paramètre dwFlags : |
| FORMAT_MESSAGE_FROM_HMODULE |
Cette valeur permet d'indiquer que lpSource est un hModule du module contenant la table de messages à rechercher. |
| FORMAT_MESSAGE_FROM_STRING |
Cette valeur permet d'indiquer que lpSource est un LPTSTR pointant vers un texte de message non formaté. Il sera analysé pour les insertions et formaté en conséquence. |
| Si aucun de ces drapeaux n'est défini dans le paramètre dwFlags, le paramètre lpSource est ignoré. |
| dwMessageId |
Ce paramètre permet d'indiquer l'identificateur de message 32 bits du message demandé. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING. |
| dwLanguageId |
Ce paramètre permet d'indiquer l'identificateur de langue 32 bits du message demandé. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING.
Si vous passez un LANGID spécifique dans ce paramètre, FormatMessageA renverra un message pour ce LANGID uniquement. Si la fonction ne peut pas trouver un message pour cette
LANGID, elle retourne ERROR_RESOURCE_LANG_NOT_FOUND. Si vous transmettez 0, FormatMessageA recherche un message pour les LANGID dans l'ordre suivant :
Langue neutre, LANGID du processus léger, basé sur les paramètres régionaux du processus léger, LANGID par défaut de l'utilisateur, basé sur 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, et l'anglais américain.
Si FormatMessage ne trouve aucun message pour aucun des LANGID ci-dessus, il renvoie toute chaîne de caractères de message de langue présente. Si même cela échoue, il retourne
ERROR_RESOURCE_LANG_NOT_FOUND. |
| lpBuffer |
Ce paramètre permet de pointeur vers un tampon pour le message formaté (et terminé par un caractère nul). Si dwFlags inclut FORMAT_MESSAGE_ALLOCATE_BUFFER, la
fonction alloue un tampon à l'aide de la fonction LocalAlloc et place l'adresse du tampon à l'adresse spécifiée dans lpBuffer. |
| nSize |
Ce paramètre permet d'indiquer si le drapeau FORMAT_MESSAGE_ALLOCATE_BUFFER n'est pas défini, ce paramètre spécifie le nombre maximal d'octets (version ANSI) ou
de caractères (version Unicode) pouvant être entreposés dans le tampon de sortie. Si FORMAT_MESSAGE_ALLOCATE_BUFFER est défini, ce paramètre spécifie le nombre minimal d'octets ou
de caractères à allouer pour un tampon de sortie. |
| Arguments |
Ce paramètre permet de pointer vers un tableau de valeurs 32 bits utilisées comme valeurs d'insertion dans le message mis en forme. %1 dans la chaîne de caractères
de format indique la première valeur du tableau Arguments; %2 indique le deuxième paramètre;.... L'interprétation de chaque valeur 32 bits dépend des informations de
formatage associées à l'insertion dans la définition du message. La valeur par défaut consiste à traiter chaque valeur en tant que pointeur sur une chaîne de caractères terminée par un
caractère NULL. Par défaut, le paramètre Arguments est du type va_list *, étant un type de données spécifique au langage et à la mise en oeuvre permettant de décrire un
nombre variable de paramètres. Si vous n'avez pas de pointeur de type va_list *, spécifiez le drapeau FORMAT_MESSAGE_ARGUMENT_ARRAY et transmettez un pointeur à un tableau
de valeurs 32 bits. Ces valeurs sont entrées dans le message sous la forme de valeurs d'insertion. Chaque insertion doit avoir un élément correspondant dans le tableau. |
Cette fonction permet de demander un message affecté par un certain format. La fonction nécessite une définition de message en entrée.
La définition du message peut provenir d'un tampon transmis à la fonction. Il peut provenir d'une ressource de table de messages d'un module déjà chargé. Ou encore, l'appelant peut demander à la
fonction de rechercher la ou les ressources de la table des messages du système pour la définition du message. La fonction trouve la définition du message dans une ressource de table de
messages en fonction d'un identifiant de message et d'un identifiant de langue. La fonction copie le texte du message formaté dans un tampon de sortie, en traitant toutes les séquences d'insertion
incorporées, si nécessaire.
