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

Статья
02/07/2025

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

Синтаксис

NTSTRSAFEDDI RtlStringCbVPrintfA(
  [out] NTSTRSAFE_PSTR  pszDest,
  [in]  size_t          cbDest,
  [in]  NTSTRSAFE_PCSTR pszFormat,
  [in]  va_list         argList
);

Параметры

[out] pszDest

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

[in] cbDest

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

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

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

[in] pszFormat

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

[in] argList

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

Замечания

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

vsprintf
vswprintf
_vsnprintf
_vsnwprintf

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

Дополнительные сведения о списках аргументов va_listтипа см. в документации по пакету SDK для Microsoft Windows.

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

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

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

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

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

Требования

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

См. также

RtlStringCbPrintf

RtlStringCbVPrintfEx

RtlStringCchVPrintf

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