wsprintfA, fonction (winuser.h)

Article
02/05/2024

Écrit les données mises en forme dans la mémoire tampon spécifiée. Tous les arguments sont convertis et copiés dans la mémoire tampon de sortie conformément à la spécification de format correspondante dans la chaîne de format. La fonction ajoute un caractère null de fin aux caractères qu’elle écrit, mais la valeur de retour n’inclut pas le caractère null de fin dans son nombre de caractères.

Note N’utilisez pas. Envisagez d’utiliser l’une des fonctions suivantes à la place : StringCbPrintf, StringCbPrintfEx, StringCchPrintf ou StringCchPrintfEx. Consultez Considérations relatives à la sécurité.

Syntaxe

int WINAPIV wsprintfA(
  [out] LPSTR  unnamedParam1,
  [in]  LPCSTR unnamedParam2,
        ...    
);

Paramètres

[out] unnamedParam1

Type : LPTSTR

Mémoire tampon qui doit recevoir la sortie mise en forme. La taille maximale de la mémoire tampon est de 1 024 octets.

[in] unnamedParam2

Type : LPCTSTR

Spécifications de contrôle de format. En plus des caractères ASCII ordinaires, une spécification de format pour chaque argument apparaît dans cette chaîne. Pour plus d’informations sur la spécification du format, consultez la section Remarques.

...

Un ou plusieurs arguments facultatifs. Le nombre et le type des paramètres d’argument dépendent des spécifications de contrôle de format correspondantes dans le paramètre lpFmt .

Valeur retournée

Type : int

Si la fonction réussit, la valeur de retour correspond au nombre de caractères stockés dans la mémoire tampon de sortie, sans compter le caractère null de fin.

Si la fonction échoue, la valeur de retour est inférieure à la longueur de la sortie attendue. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La chaîne de contrôle de format contient des spécifications de format qui déterminent le format de sortie des arguments suivant le paramètre lpFmt . Les spécifications de format, décrites ci-dessous, commencent toujours par un signe de pourcentage (%). Si un signe de pourcentage est suivi d’un caractère qui n’a aucune signification en tant que champ de format, le caractère n’est pas mis en forme (par exemple, %% produit un caractère de signe de pourcentage unique).

La chaîne de contrôle de format est lue de gauche à droite. Lorsque la première spécification de format (le cas échéant) est rencontrée, la valeur du premier argument après la chaîne de contrôle de format est convertie et copiée dans la mémoire tampon de sortie en fonction de la spécification de format. La deuxième spécification de format entraîne la conversion et la copie du deuxième argument, et ainsi de suite. S’il y a plus d’arguments que de spécifications de format, les arguments supplémentaires sont ignorés. S’il n’y a pas suffisamment d’arguments pour toutes les spécifications de format, les résultats ne sont pas définis.

Une spécification de format se présente sous la forme suivante :

%[-][#][0][width][.precision]type

Chaque champ est un caractère unique ou un nombre qui signifie une option de format particulière. Les caractères de type qui apparaissent après le dernier champ de format facultatif déterminent si l’argument associé est interprété comme un caractère, une chaîne ou un nombre. La spécification de format la plus simple contient uniquement le signe de pourcentage et un caractère de type (par exemple, %s). Les champs facultatifs contrôlent d’autres aspects de la mise en forme. Voici les champs facultatifs et obligatoires et leurs significations.

Champ	Signification
-	Placez la sortie avec des blancs ou des zéros à droite pour remplir la largeur du champ, ce qui justifie la sortie à gauche. Si ce champ est omis, la sortie est remplie à gauche, ce qui le justifie à droite.
#	Préfixez les valeurs hexadécimales avec 0x (minuscules) ou 0X (majuscules).
0	Placez la valeur de sortie avec des zéros pour remplir la largeur du champ. Si ce champ est omis, la valeur de sortie est remplie d’espaces vides.
width	Copiez le nombre minimal de caractères spécifié dans la mémoire tampon de sortie. Le champ width est un entier non négatif. La spécification de largeur n’entraîne jamais la troncation d’une valeur ; si le nombre de caractères dans la valeur de sortie est supérieur à la largeur spécifiée, ou si le champ de largeur n’est pas présent, tous les caractères de la valeur sont imprimés, sous réserve de la spécification de précision.
. Précision	Pour les nombres, copiez le nombre minimal de chiffres spécifié dans la mémoire tampon de sortie. Si le nombre de chiffres dans l’argument est inférieur à la précision spécifiée, la valeur de sortie est remplie sur la gauche avec des zéros. La valeur n’est pas tronquée lorsque le nombre de chiffres dépasse la précision spécifiée. Si la précision spécifiée est 0 ou omise entièrement, ou si le point (.) apparaît sans nombre, la précision est définie sur 1. Pour les chaînes, copiez le nombre maximal de caractères spécifié dans la mémoire tampon de sortie.
type	Sortez l’argument correspondant sous la forme d’un caractère, d’une chaîne ou d’un nombre. Ce champ peut être l’une des valeurs suivantes. `c` Caractère unique. Cette valeur est interprétée comme type CHAR par wsprintfA et type WCHAR par wsprintfW. Remarque wsprintf est une macro définie comme wsprintfA (Unicode non défini) ou wsprintfW (Défini par Unicode). `C` Caractère unique. Cette valeur est interprétée comme type WCHAR par wsprintfA et type CHAR par wsprintfW. Remarque wsprintf est une macro définie comme wsprintfA (Unicode non défini) ou wsprintfW (Défini par Unicode). `d` Entier décimal signé. Cette valeur est équivalente à `i`. `hc`, `hC` Caractère unique. Si le caractère a une valeur numérique de zéro, il est ignoré. Cette valeur est toujours interprétée comme du type CHAR, même lorsque l’application appelante définit Unicode. `hd` Argument entier court signé. `hs`, `hS` Chaîne. Cette valeur est toujours interprétée comme étant de type LPSTR, même lorsque l’application appelante définit Unicode. `hu` Entier court non signé. `i` Entier décimal signé. Cette valeur est équivalente à `d`. `Ix`, `IX` Entier hexadécimal non signé 64 bits en minuscules ou majuscules sur les plateformes 64 bits, entier hexadécimal 32 bits non signé en minuscules ou majuscules sur les plateformes 32 bits. `lc`, `lC` Caractère unique. Si le caractère a une valeur numérique de zéro, il est ignoré. Cette valeur est toujours interprétée comme étant de type WCHAR, même lorsque l’application appelante définit Unicode. `ld` Entier signé long. Cette valeur est équivalente à `li`. `li` Entier signé long. Cette valeur est équivalente à `ld`. `ls`, `lS` Chaîne. Cette valeur est toujours interprétée comme étant de type LPWSTR, même lorsque l’application appelante ne définit pas Unicode. Cette valeur est équivalente à `ws`. `lu` Entier non signé long. `lx`, `lX` Entier hexadécimal non signé long en minuscules ou majuscules. `p` Pointeur. L’adresse est imprimée en hexadécimal. `s` Chaîne. Cette valeur est interprétée comme type LPSTR par wsprintfA et type LPWSTR par wsprintfW. Remarque wsprintf est une macro définie comme wsprintfA (Unicode non défini) ou wsprintfW (Défini par Unicode). `S` Chaîne. Cette valeur est interprétée comme type LPWSTR par wsprintfA et type LPSTR par wsprintfW. Remarque wsprintf est une macro définie comme wsprintfA (Unicode non défini) ou wsprintfW (Défini par Unicode). `u` Argument entier non signé. `x`, `X` Entier hexadécimal non signé en minuscules ou majuscules.

Note Il est important de noter que wsprintf utilise la convention d’appel C (_cdecl) plutôt que la convention d’appel standard (_stdcall). Par conséquent, il est de la responsabilité du processus appelant de faire apparaître les arguments hors de la pile, et les arguments sont envoyés de droite à gauche sur la pile. Dans les modules en langage C, le compilateur C effectue cette tâche.

Pour utiliser des mémoires tampons supérieures à 1 024 octets, utilisez _snwprintf. Pour plus d’informations, consultez la documentation de la bibliothèque runtime C.

Notes

L’en-tête winuser.h définit wsprintf en tant qu’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. La combinaison 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 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll