Функция wsprintfW (winuser.h)

Статья
01/27/2024

Записывает отформатированные данные в указанный буфер. Все аргументы преобразуются и копируются в выходной буфер в соответствии с соответствующей спецификацией формата в строке формата. Функция добавляет завершающий пустой символ к символам, которые она записывает, но возвращаемое значение не включает завершающий пустой символ в число символов.

Примечание Не используйте. Рассмотрите возможность использования одной из следующих функций: StringCbPrintf, StringCbPrintfEx, StringCchPrintf или StringCchPrintfEx. См. раздел Вопросы безопасности.

Синтаксис

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

Параметры

[out] unnamedParam1

Тип: LPTSTR

Буфер, который принимает форматированные выходные данные. Максимальный размер буфера составляет 1024 байта.

[in] unnamedParam2

Тип: LPCTSTR

Спецификации элемента управления форматированием. В дополнение к обычным символам ASCII в этой строке отображается спецификация формата для каждого аргумента. Дополнительные сведения о спецификации формата см. в разделе Примечания.

...

Один или несколько необязательных аргументов. Количество и тип параметров аргумента зависят от соответствующих спецификаций элемента управления форматом в параметре lpFmt .

Возвращаемое значение

Тип: int

Если функция выполнена успешно, возвращаемое значение — это количество символов, хранящихся в выходном буфере, не считая завершающего символа NULL.

Если функция завершается сбоем, возвращаемое значение меньше ожидаемой длины выходных данных. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Строка элемента управления форматированием содержит спецификации формата, определяющие формат выходных данных для аргументов, следующих за параметром lpFmt . Спецификации формата, рассмотренные ниже, всегда начинаются со знака процента (%). Если за знаком процента следует символ, который не имеет значения в качестве поля формата, символ не форматируется (например, %% создает один знак процента).

Строка элемента управления форматом считывается слева направо. При обнаружении первой спецификации формата (при наличии) значение первого аргумента после строки элемента управления форматированием преобразуется и копируется в выходной буфер в соответствии со спецификацией формата. Вторая спецификация формата приводит к преобразованию и копированию второго аргумента и т. д. Если аргументов больше, чем спецификаций формата, дополнительные аргументы игнорируются. Если аргументов недостаточно для всех спецификаций формата, результаты будут неопределенными.

Спецификация формата имеет следующий вид:

%[-][#][0][ширина][.precision]тип

Каждое поле представляет собой один символ или число, обозначающее определенный параметр формата. Символы типа , отображаемые после последнего необязательного поля формата, определяют, интерпретируется ли связанный аргумент как символ, строка или число. Простейшая спецификация формата содержит только знак процента и символ типа (например, %s). Необязательные поля управляют другими аспектами форматирования. Ниже приведены необязательные и обязательные поля и их значения.

Поле	Значение
-	Заполните выходные данные пробелами или нулями справа, чтобы заполнить ширину поля, оправдывая выходные данные слева. Если это поле опущено, выходные данные заполняются слева, оправдывая их справа.
#	Префикс шестнадцатеричных значений с 0x (нижний регистр) или 0X (верхний регистр).
0	Заполните выходное значение нулями, чтобы заполнить ширину поля. Если это поле не указано, выходное значение заполняется пустыми пробелами.
width	Скопируйте указанное минимальное количество символов в выходной буфер. Поле ширины является неотрицательным целым числом. Спецификация ширины никогда не приводит к усечению значения; Если число символов в выходном значении больше указанной ширины или если поле ширины отсутствует, печатаются все символы значения в соответствии со спецификацией точности.
. Точность	Для чисел скопируйте указанное минимальное число цифр в выходной буфер. Если число цифр в аргументе меньше указанной точности, выходное значение заполняется слева нулями. Значение не усекается, если число цифр превышает указанную точность. Если заданная точность равна 0 или полностью опущена, или если точка (.) отображается без следующего за ней числа, точность устанавливается равным 1. Для строк скопируйте указанное максимальное число символов в выходной буфер.
type	Выводит соответствующий аргумент в виде символа, строки или числа. Это поле может быть любым из следующих значений. `c` Один символ. Это значение интерпретируется как тип CHARв wsprintfA , а тип WCHAR — wsprintfW. Обратите внимание , что wsprintf — это макрос, определенный как wsprintfA (юникод не определен) или wsprintfW (определено в Юникоде). `C` Один символ. Это значение интерпретируется как тип WCHARв wsprintfA , а тип CHAR — wsprintfW. Обратите внимание , что wsprintf — это макрос, определенный как wsprintfA (юникод не определен) или wsprintfW (определено в Юникоде). `d` Десятичное целое число со знаком. Это значение эквивалентно `i`. `hc`, `hC` Один символ. Если символ имеет числовое значение, равное нулю, он игнорируется. Это значение всегда интерпретируется как тип CHAR, даже если вызывающее приложение определяет Юникод. `hd` Короткий целочисленный аргумент со знаком. `hs`, `hS` Строка. Это значение всегда интерпретируется как тип LPSTR, даже если вызывающее приложение определяет Юникод. `hu` Короткое целое число без знака. `i` Десятичное целое число со знаком. Это значение эквивалентно `d`. `Ix`, `IX` 64-разрядное шестнадцатеричное целое число без знака в нижнем или верхнем регистре на 64-разрядных платформах, 32-разрядное шестнадцатеричное целое число без знака в нижнем или верхнем регистре на 32-разрядных платформах. `lc`, `lC` Один символ. Если символ имеет числовое значение, равное нулю, он игнорируется. Это значение всегда интерпретируется как тип WCHAR, даже если вызывающее приложение определяет Юникод. `ld` Длинное целое число со знаком. Это значение эквивалентно `li`. `li` Длинное целое число со знаком. Это значение эквивалентно `ld`. `ls`, `lS` Строка. Это значение всегда интерпретируется как тип LPWSTR, даже если вызывающее приложение не определяет Юникод. Это значение эквивалентно `ws`. `lu` Длинное целое число без знака. `lx`, `lX` Длинное шестнадцатеричное целое число без знака в нижнем или верхнем регистре. `p` Указатель. Адрес выводится в шестнадцатеричном формате. `s` Строка. Это значение интерпретируется как тип LPSTRв wsprintfA и тип LPWSTRв wsprintfW. Обратите внимание , что wsprintf — это макрос, определенный как wsprintfA (юникод не определен) или wsprintfW (определено в Юникоде). `S` Строка. Это значение интерпретируется как тип LPWSTRв wsprintfA и тип LPSTR в wsprintfW. Примечание . Wsprintf — это макрос, определенный как wsprintfA (Юникод не определен) или wsprintfW (определен в Юникоде). `u` Аргумент целого числа без знака. `x`, `X` Шестнадцатеричное целое число без знака в нижнем или верхнем регистре.

Примечание Важно отметить, что wsprintf использует соглашение о вызовах C (_cdecl), а не стандартное соглашение о вызовах (_stdcall). В результате вызывающий процесс отвечает за вывод аргументов из стека, а аргументы отправляются в стек справа налево. В модулях языка C эту задачу выполняет компилятор C.

Чтобы использовать буферы размером более 1024 байт, используйте _snwprintf. Дополнительные сведения см. в документации по библиотеке времени выполнения C.

Примечание

Заголовок winuser.h определяет wsprintf как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll