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

Статья
05/03/2024

Функции 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, которая содержит директивы форматирования в стиле printf.

...

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

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

Строковый тип данных	Строковый литерал	Функция
WCHAR	L"string"	RtlStringCbPrintfW
char	Строка	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 (включая Ntstrsafe.h)
Библиотека	Ntstrsafe.lib
IRQL	Любое значение, если строки, которыми осуществляется управление, всегда находятся в памяти, в противном случае PASSIVE_LEVEL

См. также раздел

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchPrintf