Le Centre W..D..

Meilleure résolution
mode 800 x 600

Optimisé pour
IE v.5
Netscape v.6
mais surtout pour
Mozilla v.1
minimum

Membre de Click-FR®, Réseau francophone Paie-Par-Click

FormatMessage

Date de parution : 25/03/2000 - Cette fiche API a été lue 1727 fois

Description

FormatMessage formate une chaîne message. La fonction demande une définition de message en entrée. La définition de message peut venir d'un tampon passée dans la fonction. Cela peut venir d'une ressource situé dans une table de messages dans un module préchargé. L'appelant peut aussi demander à la fonction de rechercher la ressource de la table des messages système pour la définition. La fonction trouve cette définition dans une ressource table de messages basée sur un identifiant de message et de langage. La fonction copie enfin le texte du message formaté dans un tampon de sortie.

Syntaxe

AppelDLL32("kernel32","FormatMessageA", dwFlags, &lpSource , dwMessageId, dwLanguageId, &lpBuffer, nSize, &Arguments)

dwFlags

Contient un jeu de sémaphore qui spécifie les aspects du processus formaté et comment interpréter le paramètre lpSource. L'octet de poids faible de dwFlags précise comment les handles de fin de lignes seront dans le tampon de sortie. Cet octet peut aussi préciser la longueur maximum de la chaîne formatée en sortie.

Vous pouvez spécifier une combinaison des valeurs suivantes :

FORMAT_MESSAGE_ALLOCATE_BUFFER = 256
Précise que le paramètre lpBuffer est un pointeur vers un pointeur de type entier long et dont le paramètre nSize précise le nombre minimum d'octets (version ANSI) ou de caractères (version Unicode) pour l'allocation du tampon de sortie du message. La fonction alloue un tampon assez large pour contenir le message formaté et placer un pointeur pour l'adressage du tampon spécifié par lpBuffer. L'appelant devra utiliser la fonction LocalFree pour libérer le tampon.

FORMAT_MESSAGE_IGNORE_INSERTS = 512
Précise quelles séquences dans la définition du message seront ignorées et passeront à travers le tampon de sortie sans changement. Ce sémaphore est utilisé pour ramener un message à formater plus tard. Si celui-ci est mis, le paramètre Arguments est ignoré.

FORMAT_MESSAGE_FROM_STRING = 1024
Précise que lpSource est un pointeur vers une chaîne à terminateur nul. La définition du message peut contenir des séquences d'insertion comme le texte du message dans une table de ressources. Peut être utilisé avec FORMAT_MESSAGE_FROM_HMODULE ou FORMAT_MESSAGE_FROM_SYSTEM.

FORMAT_MESSAGE_FROM_HMODULE = 2048
Précise que lpSource est un handle contenant la table de ressources des messages à rechercher. Peut être utilisé avec FORMAT_MESSAGE_FROM_STRING.

FORMAT_MESSAGE_FROM_SYSTEM = 4096
Précise que la fonction devra rechercher le message demandé dans une table de ressources message système. Si ce sémaphore est spécifié avec FORMAT_MESSAGE_FROM_HMODULE, la fonction recherche le message système si celui-ci n'est pas trouvé dans le module spécifié par lpSource.
Peut être utilisé avec FORMAT_MESSAGE_FROM_STRING. Si ce sémaphore est précisé, une application peut passer le résultat de GetLastError pour y retrouver le texte du message pour une erreur système définie.

FORMAT_MESSAGE_ARGUMENT_ARRAY = 8192
Précise que le paramètre Arguments n'est pas une structure mais pointe sur un tableau d'arguments de valeur 32 bits.

FORMAT_MESSAGE_MAX_WIDTH_MASK = 255
La fonction ignore le retour à la ligne du texte du message. La fonction stocke ce code en dur dans la définition du message pour le tampon de sortie. La fonction ne génère pas de nouveau retour à la ligne.

lpSource

Précise le lieu de la définition du message. Le type de ce paramètre dépend de ceux de dwFlags.

dwFlags	Paramètre
FORMAT_MESSAGE_FROM_HMODULE	lpSource est un hModule du module qui contient la table des messages à rechercher.
FORMAT_MESSAGE_FROM_STRING	lpSource est une chaîne qui pointe vers un texte non formaté.

Si aucun de ces sémaphores n'est mis dans dwFlags, lpSource est ignoré.

dwMessageId

Précise l'identifiant 32 bits du message pour la requête. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING.

dwLanguageId

Précise l'identifiant du langage pour le message. Ce paramètre est ignoré si dwFlags inclut FORMAT_MESSAGE_FROM_STRING.

lpBuffer

Pointe sur un tampon pour le message formaté (et son terminateur nul).

nSize

Si le sémaphore FORMAT_MESSAGE_ALLOCATE_BUFFER n'est pas mis, ce paramètre précise le nombre maximum d'octets (version ANSI) ou de caractères (version Unicode) qui peut être stocké dans le tampon de sortie.
Si FORMAT_MESSAGE_ALLOCATE_BUFFER est mis, ce paramètre précise le nombre minimum d'octets ou de caractères à allouer pour le tampon de sortie.

Arguments

Pointe sur un tableau de valeurs sur 32 bits qui sont utilisées pour insérer des valeurs dans le message formaté. %1 dans la chaîne indique la première valeur dans le tableau, %2 la seconde, etc.

Compatibilité

Win32s, Win9x, WinNT, Win2000

Remarque

Aucune

Exemple 1

// Afficher un message résultant d'une erreur d'une fonction API // Res est le résultat de cette fonction


FONCTION ErreurAPI(Res = 0)
Buffer est une chaîne asciiz sur 512

MessageBuffer est un entier long = 
&Buffer

BuffSize est un entier long

FormatFlags est un entier long = 0x1200

hModule est un entier long
hModule = 
ChargeDLL("netmsg") 

SI hModule ALORS 
FormatFlags += 0x800
BuffSize = 
AppelDLL32("kernel32", 
"FormatMessageA", ...

FormatFlags, 
hModule, 
Res, 0, 
MessageBuffer, 512, 
Null)
SI 
hModule 
ALORS DechargeDLL(hModule)
RENVOYER Buffer

Nombre de commentaire sur FormatMessage : 0

Rappel : Le code fourni est compatible Windev v.4 et 5. Pour les versions supérieures, vous devez modifier le type des variables numériques. Par exemple : entier long devient entier.
Bien sûr, les marques citées sont déposées par leurs sociétés respectives. Ces pages sont à la disposition de tous, le code fourni est libre mais toute responsabilité est déclinée en cas de mauvais usage ou de dysfonctionnement.
© 2000-2005 Beaussier & Le Centre W..D..