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

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

Синтаксис

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

Параметры

[out] pszDest

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

[in] cchDest

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

[in] pszFormat

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

[in] argList

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

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

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

Код возврата	Описание
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 см. в документации по Microsoft Windows SDK.

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

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

 

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

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

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

Требования

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

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

RtlStringCbVPrintf

RtlStringCchPrintf

RtlStringCchVPrintfEx