Función wsprintfW (winuser.h)

Artículo
02/01/2024

Escribe datos con formato en el búfer especificado. Los argumentos se convierten y copian en el búfer de salida según la especificación de formato correspondiente en la cadena de formato. La función anexa un carácter nulo de terminación a los caracteres que escribe, pero el valor devuelto no incluye el carácter nulo de terminación en su recuento de caracteres.

Nota No use. Considere la posibilidad de usar una de las siguientes funciones en su lugar: StringCbPrintf, StringCbPrintfEx, StringCchPrintf o StringCchPrintfEx. Consulte Consideraciones de seguridad.

Sintaxis

int WINAPIV wsprintfW(
  [out] LPWSTR  unnamedParam1,
  [in]  LPCWSTR unnamedParam2,
        ...     
);

Parámetros

[out] unnamedParam1

Tipo: LPTSTR

Búfer que va a recibir la salida con formato. El tamaño máximo del búfer es de 1024 bytes.

[in] unnamedParam2

Tipo: LPCTSTR

Las especificaciones de control de formato. Además de los caracteres ASCII normales, aparece una especificación de formato para cada argumento en esta cadena. Para obtener más información sobre la especificación de formato, vea la sección Comentarios.

...

Uno o varios argumentos opcionales. El número y el tipo de parámetros de argumento dependen de las especificaciones de control de formato correspondientes en el parámetro lpFmt .

Valor devuelto

Tipo: int

Si la función se ejecuta correctamente, el valor devuelto es el número de caracteres almacenados en el búfer de salida, sin contar el carácter nulo de terminación.

Si se produce un error en la función, el valor devuelto es menor que la longitud de la salida esperada. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La cadena de control de formato contiene especificaciones de formato que determinan el formato de salida de los argumentos después del parámetro lpFmt . Las especificaciones de formato, que se describen a continuación, siempre comienzan con un signo de porcentaje (%). Si un signo de porcentaje va seguido de un carácter que no tiene ningún significado como campo de formato, el carácter no tiene formato (por ejemplo, %% genera un carácter de signo de porcentaje único).

La cadena de control de formato se lee de izquierda a derecha. Cuando se encuentra la primera especificación de formato (si existe), hace que el valor del primer argumento después de la cadena de control de formato se convierta y copie en el búfer de salida según la especificación de formato. La segunda especificación de formato hace que el segundo argumento se convierta y copie, etc. Si hay más argumentos que las especificaciones de formato, se omiten los argumentos adicionales. Si no hay suficientes argumentos para todas las especificaciones de formato, los resultados no están definidos.

Una especificación de formato tiene la forma siguiente:

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

Cada campo es un carácter único o un número que indica una opción de formato determinada. Los caracteres de tipo que aparecen después del último campo de formato opcional determinan si el argumento asociado se interpreta como un carácter, una cadena o un número. La especificación de formato más sencilla contiene solo el signo de porcentaje y un carácter de tipo (por ejemplo, %s). Los campos opcionales controlan otros aspectos del formato. A continuación se muestran los campos opcionales y obligatorios y sus significados.

Campo	Significado
-	Rellene la salida con espacios en blanco o ceros a la derecha para rellenar el ancho del campo, justificando la salida a la izquierda. Si se omite este campo, la salida se rellena a la izquierda, lo que lo justifica a la derecha.
#	Prefijo de valores hexadecimales con 0x (minúsculas) o 0X (mayúsculas).
0	Rellene el valor de salida con ceros para rellenar el ancho del campo. Si se omite este campo, el valor de salida se rellena con espacios en blanco.
width	Copie el número mínimo de caracteres especificado en el búfer de salida. El campo width es un entero no negativo. La especificación de ancho nunca hace que un valor se trunquen; si el número de caracteres del valor de salida es mayor que el ancho especificado, o si el campo width no está presente, se imprimen todos los caracteres del valor, sujeto a la especificación de precisión.
. Precisión	Para los números, copie el número mínimo de dígitos especificado en el búfer de salida. Si el número de dígitos del argumento es menor que la precisión especificada, el valor de salida se rellena a la izquierda con ceros. El valor no se trunca cuando el número de dígitos supera la precisión especificada. Si la precisión especificada es 0 o se omite por completo, o si el punto (.) aparece sin un número después, la precisión se establece en 1. Para las cadenas, copie el número máximo de caracteres especificado en el búfer de salida.
type	Genera el argumento correspondiente como un carácter, una cadena o un número. Este campo puede ser cualquiera de los valores siguientes. `c` Carácter único. Este valor se interpreta como el tipo CHAR por wsprintfA y el tipo WCHAR por wsprintfW. Nota wsprintf es una macro definida como wsprintfA (unicode no definido) o wsprintfW (unicode definido). `C` Carácter único. Este valor se interpreta como tipo WCHAR por wsprintfA y el tipo CHAR por wsprintfW. Nota wsprintf es una macro definida como wsprintfA (unicode no definido) o wsprintfW (unicode definido). `d` Entero decimal con signo. Este valor es equivalente a `i`. `hc`, `hC` Carácter único. Si el carácter tiene un valor numérico de cero, se omite. Este valor siempre se interpreta como de tipo CHAR, incluso cuando la aplicación que realiza la llamada define Unicode. `hd` Argumento entero corto con signo. `hs`, `hS` String. Este valor siempre se interpreta como tipo LPSTR, incluso cuando la aplicación que realiza la llamada define Unicode. `hu` Entero corto sin signo. `i` Entero decimal con signo. Este valor es equivalente a `d`. `Ix`, `IX` Entero hexadecimal sin signo de 64 bits en minúsculas o mayúsculas en plataformas de 64 bits, entero hexadecimal sin signo de 32 bits en minúsculas o en mayúsculas en plataformas de 32 bits. `lc`, `lC` Carácter único. Si el carácter tiene un valor numérico de cero, se omite. Este valor siempre se interpreta como tipo WCHAR, incluso cuando la aplicación que realiza la llamada define Unicode. `ld` Entero con signo largo. Este valor es equivalente a `li`. `li` Entero con signo largo. Este valor es equivalente a `ld`. `ls`, `lS` Cadena Este valor siempre se interpreta como tipo LPWSTR, incluso cuando la aplicación que realiza la llamada no define Unicode. Este valor es equivalente a `ws`. `lu` Entero largo sin signo. `lx`, `lX` Entero hexadecimal sin signo largo en minúsculas o mayúsculas. `p` Puntero. La dirección se imprime mediante hexadecimal. `s` Cadena Este valor se interpreta como tipo LPSTR por wsprintfA y el tipo LPWSTR por wsprintfW. Nota wsprintf es una macro definida como wsprintfA (unicode no definido) o wsprintfW (unicode definido). `S` Cadena Este valor se interpreta como el tipo LPWSTR por wsprintfA y el tipo LPSTR por wsprintfW. Nota wsprintf es una macro definida como wsprintfA (unicode no definido) o wsprintfW (unicode definido). `u` Argumento entero sin signo. `x`, `X` Entero hexadecimal sin signo en minúsculas o mayúsculas.

Nota Es importante tener en cuenta que wsprintf usa la convención de llamada de C (_cdecl), en lugar de la convención de llamada estándar (_stdcall). Como resultado, es responsabilidad del proceso de llamada extraer los argumentos de la pila y los argumentos se insertan en la pila de derecha a izquierda. En los módulos del lenguaje C, el compilador de C realiza esta tarea.

Para usar búferes de más de 1024 bytes, use _snwprintf. Para obtener más información, consulte la documentación de la biblioteca en tiempo de ejecución de C.

Nota

El encabezado winuser.h define wsprintf como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll