Écrit des 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 en fonction de 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.
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 de format, consultez la section Remarques.
...
Un ou plusieurs arguments facultatifs. Le nombre et le type de paramètres d’argument dépendent des spécifications de contrôle de format correspondantes dans le paramètre lpFmt.
Valeur de retour
Type : int
Si la fonction réussit, la valeur de retour est le 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’erreur étendues, 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. 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 comme 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 conversion et la copie de la chaîne de contrôle de format 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 existe plus d’arguments que de spécifications de format, les arguments supplémentaires sont ignorés. S’il n’existe pas suffisamment d’arguments pour toutes les spécifications de format, les résultats ne sont pas définis.
Une spécification de format présente la forme suivante :
%[-][#][0][width][.precision]type
Chaque champ est un caractère unique ou un nombre signalant une option de format particulière. Le type caractères qui apparaissent après le dernier champ de format facultatif détermine 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 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
-
Remplissez la sortie avec des vides 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 rembourrée à gauche, ce qui le justifie à droite.
#
Préfixer des valeurs hexadécimales avec 0x (minuscules) ou 0X (majuscules).
0
Remplissez 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.
largeur
Copiez le nombre minimal spécifié de caractères dans la mémoire tampon de sortie. Le champ largeur 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 largeur n’est pas présent, tous les caractères de la valeur sont imprimés, soumis à la spécification de précision.
.précision
Pour les nombres, copiez le nombre minimal spécifié de chiffres 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 la période (.) apparaît sans nombre suivant, 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
Affichez 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 un type CHAR par wsprintfA et le type WCHAR par wsprintfW. Notez wsprintf est une macro définie comme wsprintfA (Unicode non définie) ou wsprintfW (défini par Unicode).
C
Caractère unique. Cette valeur est interprétée comme un type WCHAR par wsprintfA et le type CHAR par wsprintfW. Notez wsprintf est une macro définie comme wsprintfA (Unicode non définie) ou wsprintfW (défini par Unicode).
d
Entier décimal signé. Cette valeur équivaut à 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 un type char, même lorsque l’application appelante définit Unicode.
hd
Argument entier court signé.
hs, hS
Corde. Cette valeur est toujours interprétée comme un type LPSTR, même lorsque l’application appelante définit Unicode.
hu
Entier court non signé.
i
Entier décimal signé. Cette valeur équivaut à d.
Ix, IX
Entier hexadécimal non signé 64 bits en minuscules ou en majuscules sur les plateformes 64 bits, entier hexadécimal non signé 32 bits en minuscules ou en 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 un type WCHAR, même lorsque l’application appelante définit Unicode.
ld
Entier signé long. Cette valeur équivaut à li.
li
Entier signé long. Cette valeur équivaut à ld.
ls, lS
Corde. Cette valeur est toujours interprétée comme un type LPWSTR, même lorsque l’application appelante ne définit pas Unicode. Cette valeur équivaut à ws.
lu
Entier non signé long.
lx, lX
Entier hexadécimal non signé long en minuscules ou en majuscules.
p
Pointeur. L’adresse est imprimée à l’aide d’un hexadécimal.
s
Corde. Cette valeur est interprétée comme type LPSTR par wsprintfA et le type LPWSTR par wsprintfW. Notez wsprintf est une macro définie comme wsprintfA (Unicode non définie) ou wsprintfW (défini par Unicode).
S
Corde. Cette valeur est interprétée comme un type LPWSTR par wsprintfA et le type LPSTR par wsprintfW. Notez wsprintf est une macro définie comme wsprintfA (Unicode non définie) ou wsprintfW (défini par Unicode).
u
Argument entier non signé.
x, X
Entier hexadécimal non signé en minuscules ou en majuscules.
Remarque 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 incombe au processus appelant de désactiver les arguments de la pile et les arguments sont envoyés sur la pile de droite à gauche. Dans les modules de 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 d’exécution C.
Note
L’en-tête winuser.h définit wsprintf comme 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.
Exigences
Exigence
Valeur
client minimum pris en charge
Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge
Windows 2000 Server [applications de bureau uniquement]