funzione wsprintfA (winuser.h)

Articolo
02/01/2024

Scrive i dati formattati nel buffer specificato. Tutti gli argomenti vengono convertiti e copiati nel buffer di output in base alla specifica di formato corrispondente nella stringa di formato. La funzione aggiunge un carattere null terminante ai caratteri scritti, ma il valore restituito non include il carattere Null terminante nel numero di caratteri.

Nota Non usare. È consigliabile usare una delle funzioni seguenti: StringCbPrintf, StringCbPrintfEx,StringCchPrintf o StringCchPrintfEx. Vedere Considerazioni sulla sicurezza.

Sintassi

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

Parametri

[out] unnamedParam1

Tipo: LPTSTR

Buffer che deve ricevere l'output formattato. La dimensione massima del buffer è di 1.024 byte.

[in] unnamedParam2

Tipo: LPCTSTR

Specifiche del controllo del formato. Oltre ai caratteri ASCII normali, viene visualizzata una specifica di formato per ogni argomento in questa stringa. Per altre informazioni sulla specifica del formato, vedere la sezione Osservazioni.

...

Uno o più argomenti facoltativi. Il numero e il tipo di parametri di argomento dipendono dalle specifiche del controllo formato corrispondenti nel parametro lpFmt .

Valore restituito

Tipo: int

Se la funzione ha esito positivo, il valore restituito è il numero di caratteri archiviati nel buffer di output, senza contare il carattere null terminante.

Se la funzione ha esito negativo, il valore restituito è minore della lunghezza dell'output previsto. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La stringa di controllo formato contiene specifiche di formato che determinano il formato di output per gli argomenti che seguono il parametro lpFmt . Le specifiche di formato, illustrate di seguito, iniziano sempre con un segno percentuale (%). Se un segno percentuale viene seguito da un carattere che non ha alcun significato come campo di formato, il carattere non viene formattato (ad esempio, %% produce un carattere di segno percentuale singolo).

La stringa di controllo del formato viene letto da sinistra a destra. Quando viene rilevata la prima specifica di formato (se presente), il valore del primo argomento dopo la conversione e la copia della stringa di controllo formato nel buffer di output in base alla specifica del formato. La seconda specifica di formato causa la conversione e la copia del secondo argomento e così via. Se sono presenti più argomenti rispetto alle specifiche di formato, gli argomenti aggiuntivi vengono ignorati. Se non sono presenti argomenti sufficienti per tutte le specifiche di formato, i risultati non sono definiti.

Una specifica di formato presenta la forma seguente:

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

Ogni campo è un singolo carattere o un numero che indica un'opzione di formato specifica. I caratteri di tipo visualizzati dopo l'ultimo campo di formato facoltativo determinano se l'argomento associato viene interpretato come carattere, una stringa o un numero. La specifica di formato più semplice contiene solo il segno percentuale e un carattere di tipo ,ad esempio %s. I campi facoltativi controllano altri aspetti della formattazione. Di seguito sono riportati i campi facoltativi e obbligatori e i relativi significati.

Campo	Significato
-	Inserire l'output con spazi vuoti o zero a destra per riempire la larghezza del campo, giustificando l'output a sinistra. Se questo campo viene omesso, l'output viene riempito a sinistra, giustificandolo a destra.
#	Valori esadecimali con 0x (minuscolo) o 0X (maiuscolo).
0	Inserire il valore di output con zero per riempire la larghezza del campo. Se questo campo viene omesso, il valore di output viene riempito con spazi vuoti.
width	Copiare il numero minimo di caratteri specificato nel buffer di output. Il campo di larghezza è un intero nonnegative. La specifica di larghezza non causa mai il troncamento di un valore; se il numero di caratteri nel valore di output è maggiore della larghezza specificata o se il campo di larghezza non è presente, tutti i caratteri del valore vengono stampati, soggetti alla specifica di precisione.
. Precisione	Per i numeri, copiare il numero minimo specificato di cifre nel buffer di output. Se il numero di cifre nell'argomento è minore della precisione specificata, il valore di output viene riempito a sinistra con zero. Il valore non viene troncato quando il numero di cifre supera la precisione specificata. Se la precisione specificata è 0 o omessa interamente o se il periodo (.) viene visualizzato senza un numero seguente, la precisione viene impostata su 1. Per le stringhe, copiare il numero massimo di caratteri specificato nel buffer di output.
type	Restituisce l'argomento corrispondente come carattere, una stringa o un numero. Questo campo può essere uno dei valori seguenti. `c` Carattere singolo. Questo valore viene interpretato come tipo CHAR da wsprintfA e tipo WCHAR by wsprintfW. Nota wsprintf è una macro definita come wsprintfA (Unicode non definito) o wsprintfW (unicode definito). `C` Carattere singolo. Questo valore viene interpretato come tipo WCHAR per wsprintfA e digitare CHAR per wsprintfW. Nota wsprintf è una macro definita come wsprintfA (Unicode non definito) o wsprintfW (unicode definito). `d` Intero decimale con segno. Questo valore equivale a `i`. `hc`, `hC` Carattere singolo. Se il carattere ha un valore numerico pari a zero, viene ignorato. Questo valore viene sempre interpretato come tipo CHAR, anche quando l'applicazione chiamante definisce Unicode. `hd` Argomento intero con segno breve. `hs`, `hS` Stringa. Questo valore viene sempre interpretato come tipo LPSTR, anche quando l'applicazione chiamante definisce Unicode. `hu` Intero corto senza segno. `i` Intero decimale con segno. Questo valore equivale a `d`. `Ix`, `IX` Intero esadecimale senza segno a 64 bit in minuscolo o maiuscolo su piattaforme a 64 bit, intero esadecimale senza segno a 32 bit in minuscolo o maiuscolo su piattaforme a 32 bit. `lc`, `lC` Carattere singolo. Se il carattere ha un valore numerico pari a zero, viene ignorato. Questo valore viene sempre interpretato come tipo WCHAR, anche quando l'applicazione chiamante definisce Unicode. `ld` Intero con segno lungo. Questo valore equivale a `li`. `li` Intero con segno lungo. Questo valore equivale a `ld`. `ls`, `lS` Stringa. Questo valore viene sempre interpretato come tipo LPWSTR, anche quando l'applicazione chiamante non definisce Unicode. Questo valore equivale a `ws`. `lu` Intero senza segno lungo. `lx`, `lX` Intero esadecimale lungo senza segno in lettere minuscole o maiuscole. `p` Puntatore. L'indirizzo viene stampato usando esadecimale. `s` Stringa. Questo valore viene interpretato come tipo LPSTR da wsprintfA e tipo LPWSTR da wsprintfW. Nota wsprintf è una macro definita come wsprintfA (Unicode non definito) o wsprintfW (unicode definito). `S` Stringa. Questo valore viene interpretato come tipo LPWSTR da wsprintfA e tipo LPSTR by wsprintfW. Nota wsprintf è una macro definita come wsprintfA (Unicode non definito) o wsprintfW (definita da Unicode). `u` Argomento Integer senza segno. `x`, `X` Intero esadecimale senza segno in lettere minuscole o maiuscole.

Nota È importante notare che wsprintf usa la convenzione di chiamata C (_cdecl), anziché la convenzione di chiamata standard (_stdcall). Di conseguenza, è responsabilità del processo chiamante visualizzare gli argomenti dallo stack e gli argomenti vengono inseriti nello stack da destra a sinistra. Nei moduli del linguaggio C il compilatore C esegue questa attività.

Per usare buffer di dimensioni superiori a 1024 byte, usare _snwprintf. Per altre informazioni, vedere la documentazione relativa alla libreria di runtime C.

Nota

L'intestazione winuser.h definisce wsprintf come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll