Функция RtlStringCbPrintfA (ntstrsafe.h)

Статья
02/07/2025

Функции RtlStringCbPrintfW и RtlStringCbPrintfA создают строку текста с подсчетом байтов с форматированием на основе предоставленных сведений о форматировании.

Синтаксис

NTSTRSAFEDDI RtlStringCbPrintfA(
  [out] NTSTRSAFE_PSTR  pszDest,
  [in]  size_t          cbDest,
  [in]  NTSTRSAFE_PCSTR pszFormat,
        ...             
);

Параметры

[out] pszDest

Указатель на буфер, предоставленный вызывающим, который получает отформатированную строку, завершающуюся значением NULL. Функция создает эту строку из строки форматирования, предоставленной pszFormat и списка аргументов функции.

[in] cbDest

Размер целевого буфера в байтах. Буфер должен быть достаточно большим, чтобы содержать отформатированную строку, а также завершающий символ NULL.

Для строк Юникода максимальное число байтов равно NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

Для строк ANSI максимальное число байтов равно NTSTRSAFE_MAX_CCH * sizeof(char).

[in] pszFormat

Указатель на текстовую строку, завершающую значение NULL, которая содержит -styled директив форматирования.

...

Список аргументов, интерпретируемых функцией на основе директив форматирования, содержащихся в строке pszFormat.

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

Функция возвращает одно из значений NTSTATUS, перечисленных в следующей таблице. Сведения об тестировании значений NTSTATUS см. в использование значений NTSTATUS.

Возвращаемый код	Описание
STATUS_SUCCESS	Это успешно состояния означает, что исходные данные были представлены, строка была создана без усечения, а результирующий целевой буфер завершается значением NULL.
STATUS_BUFFER_OVERFLOW	Это предупреждение о состоянии означает, что операция не завершена из-за нехватки места в целевом буфере. Буфер назначения содержит усеченную версию выходной строки.
STATUS_INVALID_PARAMETER	Это ошибка состоянии означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает значение STATUS_INVALID_PARAMETER, если: Значение в cbDest больше максимального размера буфера. Буфер назначения уже заполнен. Присутствует указатель NULL. Длина целевого буфера составила нулю, но в исходной строке ненулевой длины присутствует.

Возвращаемый код

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

Это предупреждение о состоянии означает, что операция не завершена из-за нехватки места в целевом буфере. Буфер назначения содержит усеченную версию выходной строки.

STATUS_INVALID_PARAMETER

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

Функция возвращает значение STATUS_INVALID_PARAMETER, если:

Значение в cbDest больше максимального размера буфера.
Буфер назначения уже заполнен.
Присутствует указатель NULL.
Длина целевого буфера составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

RtlStringCbPrintfW и RtlStringCbPrintfA следует использовать вместо следующих функций:

спринтфа
swprintf
_snprintf
_snwprintf

Все эти функции принимают строку формата и список аргументов, интерпретируют их и создают форматированную строку. Размер в байтах целевого буфера предоставляется для RtlStringCbPrintfW и RtlStringCbPrintfA, чтобы убедиться, что они не записываются в конце буфера.

Используйте RtlStringCbPrintfW для обработки строк Юникода и RtlStringCbPrintfA для обработки строк ANSI. Используемая форма зависит от данных, как показано в следующей таблице.

Тип строковых данных	Строковый литерал	Функция
WCHAR	L"string"	RtlStringCbPrintfW
char	"string"	RtlStringCbPrintfA

Если pszDest и pszFormat указывает на перекрывающиеся строки или если какие-либо строки аргументов перекрываются, поведение функции не определено.

Ни pszFormat, ни pszDest нельзя NULL. Если необходимо обрабатывать значения указателя строки NULL, используйте RtlStringCbPrintfEx.

Дополнительные сведения о функциях безопасной строки см. в разделе Использование безопасных строковых функций.

Примеры

В следующем примере показано базовое использование RtlStringCbPrintfW с четырьмя аргументами.

int const arraysize = 30;
WCHAR pszDest[arraysize]; 
size_t cbDest = arraysize * sizeof(WCHAR);

LPCWSTR pszFormat = L"%s %d + %d = %d.";
WCHAR* pszTxt = L"The answer is";

NTSTATUS status = RtlStringCbPrintfW(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);

Результирующая строка — "Ответ равен 1 + 2 = 3". Он содержится в буфере по pszDest.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows XP с пакетом обновления 1 (SP1).
целевая платформа	Настольный
заголовка	ntstrsafe.h (include Ntstrsafe.h)
библиотеки	Ntstrsafe.lib
IRQL	Любой, если управляемые строки всегда находятся в памяти, в противном случае PASSIVE_LEVEL

См. также

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchPrintf

Поделиться через