Функция wsprintf форматирует и хранит ряд символов и значений в буфере. Любые параметры преобразуются и копируются в буфер выводимых данных согласно соответствующей спецификации формата в форматируемой строке. Функция добавляет в конец символ завершающего нуля к символам, которые она пишет, но в возвращаемом значении она не включает его в число символов.
Синтаксис
int wsprintf(LPTSTRlpOut,
LPCTSTRlpFmt,
...
);
Параметры
lpOut
[out] Указатель на буфер, который получит форматированный вывод данных. Максимальный размер буфера составляет 1024 байта.
lpFmt
[in] Указатель на строку с завершающим нулем, которая содержит в себе спецификации управления форматом. В дополнение к обычным символам ASCII спецификация формата для каждого параметра показывается в этой строке. Для получения дополнительной информации о спецификация формата см. раздел
Замечаний.
...
[in] Указывает один или несколько дополнительных параметров. Число и тип характеристик параметра зависят от соответствующих спецификаций управления форматом в параметре
lpFmt.
Возвращаемое значение
Если функция завершается успешно, возвращаемое значение - число символов, сохраненных в буфере выводимых данных, не считая символ завершающего нуля.
Если функция завершается ошибкой, возвращаемое значение меньше, чем длина ожидаемого вывода данных. Чтобы получить дополнительную информацию об ошибке, вызовите
GetLastError.
Замечания
Предупреждение защиты! Используя эту функцию неправильно можно поставить под угрозу обеспечение безопасности Вашего приложения. Строка, возвращенная в
lpOut, не гарантирована от того, что будет ЗАВЕРШЕНА СИМВОЛОМ КОНЦА СТРОКИ ('\0'). Кроме того, избегайте формата %s - он может привести к переполнению буфера. Если происходит нарушение прав доступа, оно служит причиной отказа от обслуживания опираясь на Ваше приложение. В худшем случае, взломщик защиты может вставить исполняемый код. Рассмотрите один из вариантов использования нижеследующих альтернативных
функций:
StringCbPrintf,
StringCbPrintfEx,
StringCbVPrintf,
StringCbVPrintfEx,
StringCchPrintf,
StringCchPrintfEx,
StringCchVPrintf или
StringCchVPrintfEx. Вы должны рассмотреть перед продолжением
Вопросы обеспечения безопасности: Пользовательский интерфейс Windows.
Строка управления форматом содержит спецификации формата, которые определяют формат вывода данных для параметров после
lpFmt параметра. Спецификации формата, обсужденные ниже, всегда начинаются со знака процента (%). Если знак процента сопровождается символом, у которого нет никакого значения как поля формата, символ не форматирующий (например, %% создает единичный символ знака процента).
Строка управления форматом читается слева направо. Когда первая спецификация формата (если она есть) встречается, она заставляет значение первого параметра после строки управления форматом быть преобразованным и скопированным в буфер выводимых данных согласно спецификации формата. Вторая спецификация формата заставляет второй параметр быть преобразованным и скопированным, и так далее. Если имеется больше параметров, чем в спецификации формата, дополнительные параметры игнорируются. Если имеется недостаточно параметров для всех спецификаций формата, результаты не определяются.
У спецификации формата - нижеследующая форма:
%[-][#][0][width][.precision]type
Каждое поле - единичный символ или число, показывающее конкретный вариант выбора формата. Символы типа, которые показываются после последнего дополнительного поля формата, определяют, понимается ли связанный параметр как символ, строка, или число. Самая простая спецификация формата содержит в себе только знак процента и символ типа (например, %s). Дополнительные поля управляют другими аспектами форматирования. Ниже - дополнительные и требуемые поля и их значения.
Поле
Предназначение
–
Дополняет вывод данных пробелами или нулями справа, чтобы заполнить ширину поля, выравнивая вывод налево. Если это поле пропускается, вывод дополняется налево, выравнивая его вправо.
#
Префикс шестнадцатеричного значения 0x (нижний регистр) или 0X (верхний регистр).
0
Дополняет выходное значение нулями, чтобы заполнить ширину поля. Если это поле пропускается, выходное значение дополняется пробелами.
width
Копирует указанное минимальное число символов в буфер выводимых данных. Поле width - неотрицательное целое число. Спецификация ширины никогда не заставляет значение обрезаться; если число символов в выходном значении больше, чем указанная ширина, или, если поле
width отсутствует, все значения печатаемых символов подчинены спецификации точности.
.precision
Для чисел, скопируйте указанное минимальное число цифр в буфер выводимых данных. Если число цифр в параметре меньше, чем указанная точность, выходное значение дополняется слева с нулями. Значение не обрезается, когда число цифр выходит за пределы указанной точности. Если указанная точность 0 или не включена полностью, или если точка (.) показывается без числа после нее, точность устанавливается в 1.
Для строк, скопируйте указанное максимальное число символов в буфер выводимых данных.
type
Выведите соответствующий параметр как символ, строку, или число. Это поле может быть любым из нижеследующих значений.
Значение
Предназначение
c
Единичный символ. Это значение интерпретируется как тип WCHAR, если вызывающее приложение определяет Unicode и как тип __
wchar_t в противном случае.
C
Единичный символ. Это значение интерпретируется как тип __wchar_t, если вызывающее приложение определяет Unicode и как тип WCHAR в противном случае.
d
Знаковое десятичное целое число. Это значение эквивалентно i.
hc, hC
Единичный символ. Функция wsprintf игнорирует символьные параметры с числовым значением нуля. Это значение всегда интерпретируется как тип __
wchar_t, даже тогда, когда вызывающее приложение определяет Unicode.
hd
Параметр знакового короткого целого числа.
hs, hS
Строка. Это значение всегда интерпретируется как тип LPSTR, даже тогда, когда вызывающее приложение определяет Unicode.
hu
Беззнаковое короткое целое число.
i
Знаковое десятичное целое число. Это значение эквивалентно d.
lc, lC
Единичный символ. Функция wsprintf игнорирует символьные параметры с числовым значением нуля. Это значение всегда интерпретируется как тип
WCHAR, даже тогда, когда вызывающее приложение не определяет Unicode.
ld
Знаковое длинное целое число. Это значение эквивалентно li.
li
Знаковое длинное целое число. Это значение эквивалентно ld.
ls, lS
Строка. Это значение всегда интерпретируется как тип LPWSTR, даже тогда, когда вызывающее приложение не определяет
Unicode. Это значение эквивалентно ws.
lu
Беззнаковое длинное целое число.
lx, lX
Длинное шестнадцатеричное целое число без знака в нижнем регистре или верхнем регистре.
p
Windows 2000/XP: Указатель. Адрес печатается, используя шестнадцатеричную систему.
s
Строка. Это значение интерпретируется как тип LPWSTR, когда вызывающее приложение определяет Unicode и как тип
LPSTR в противном случае.
S
Строка. Это значение интерпретируется как тип LPSTR, когда вызывающее приложение определяет Unicode и как тип
LPWSTR в противном случае.
u
Параметр целого числа без знака.
x, X
Шестнадцатеричное целое число без знака в нижнем или верхнем регистре.
Обратите внимание! Это важно! на то, что wsprintf, использует соглашение о вызовах C (_cdecl), а не стандартный вызов (_stdcall). В результате этого - ответственность вызываемого процесса извлечь из стека параметры из стека и поместить параметры в стек справа налево. В C-языковых модулях компилятор
C выполняет эту задачу.
Чтобы использовать буфера, большие, чем 1024 байта, используйте функцию _snwprintf. Для получения дополнительной информации, см. документацию для библиотеки исполняющей системы C.
Предупреждение защиты! Используя эту функцию неправильно можно поставить под угрозу обеспечение безопасности Вашего приложения. Строка, возвращенная в
lpOut, не гарантирована от того, что будет ЗАВЕРШЕНА СИМВОЛОМ КОНЦА СТРОКИ ('\0'). Кроме того, избегайте формата %s - он может привести к переполнению буфера. Если происходит нарушение прав доступа, оно служит причиной отказа от обслуживания опираясь на Ваше приложение. В худшем случае, взломщик защиты может вставить исполняемый код. Рассмотрите один из вариантов использования нижеследующих альтернативных
функций:
StringCbPrintf,
StringCbPrintfEx,
StringCbVPrintf,
StringCbVPrintfEx,
StringCchPrintf,
StringCchPrintfEx,
StringCchVPrintf или
StringCchVPrintfEx. Вы должны рассмотреть перед продолжением
Вопросы обеспечения безопасности: Пользовательский интерфейс Windows.
Обратите внимание! Это важно! на то, что wsprintf, использует соглашение о вызовах C (_cdecl), а не стандартный вызов (_stdcall). В результате этого - ответственность вызываемого процесса извлечь из стека параметры из стека и поместить параметры в стек справа налево. В C-языковых модулях компилятор
C выполняет эту задачу.