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

Статья
01/27/2024

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

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

Синтаксис

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

Параметры

[out] unnamedParam1

Тип: LPTSTR

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

[in] unnamedParam2

Тип: LPCTSTR

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

...

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

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

Тип: int

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

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

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

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

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

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

Каждое поле представляет собой один символ или число, обозначающее определенный параметр формата. Символы типа , отображаемые после последнего необязательного поля формата, определяют, интерпретируется ли связанный аргумент как символ, строка или число. Самая простая спецификация формата содержит только знак процента и символ типа (например, %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