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

Статья
02/07/2025

RtlStringCchVPrintfW и функции RtlStringCchVPrintfA создают текстовую строку с подсчетом символов с форматированием, основанной на предоставленной информации о форматировании.

Синтаксис

NTSTRSAFEDDI RtlStringCchVPrintfW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cchDest,
  [in]  NTSTRSAFE_PCWSTR pszFormat,
  [in]  va_list          argList
);

Параметры

[out] pszDest

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

[in] cchDest

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

[in] pszFormat

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

[in] argList

Список аргументов va_listтипа. Аргументы, содержащиеся в списке аргументов, будут интерпретированы с помощью строки форматирования, предоставленной pszFormat.

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

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

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

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

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

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

Замечания

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

vsprintf
vswprintf
_vsnprintf
_vsnwprintf

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

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

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

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

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

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

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

Требования

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

См. также

RtlStringCbVPrintf

RtlStringCchPrintf

RtlStringCchVPrintfEx

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