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

Статья
02/29/2024

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

Синтаксис

NTSTRSAFEDDI RtlStringCchVPrintfExW(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cchDest,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcchRemaining,
  [in]            DWORD            dwFlags,
  [in, optional]  NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Параметры

[out] pszDest

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

[in] cchDest

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

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

Один или несколько флагов и, при необходимости, байт заливки. Флаги определяются следующим образом.

Значение	Значение
STRSAFE_FILL_BEHIND_NULL	Если задано и функция выполняется успешно, для заполнения части буфера назначения, следующей за символом NULL, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS	Если этот параметр задан, pszDest может иметь значение NULL. Указатели nullpszDest не могут получать непустые строки.
STRSAFE_FILL_ON_FAILURE	Если задано и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags , а буфер завершается со значением NULL. Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NULL_ON_FAILURE	Если задано и функция завершается сбоем, буфер назначения устанавливается в пустую строку (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NO_TRUNCATION	Если задано и функция возвращает STATUS_BUFFER_OVERFLOW, содержимое буфера назначения не изменяется.

[in, optional] pszFormat

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

[in] argList

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Это состояние успешного выполнения означает, что исходные данные присутствовали, выходная строка была создана без усечения, а результирующий буфер назначения завершается null.
STATUS_BUFFER_OVERFLOW	Это состояние предупреждения означает, что операция не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано в dwFlags, целевой буфер не изменяется. Если флаг не задан, буфер назначения содержит усеченную версию созданной строки.
STATUS_INVALID_PARAMETER	Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает значение STATUS_INVALID_PARAMETER в следующих случаях: Указан недопустимый флаг. Значение в cchDest больше максимального размера буфера. Целевой буфер уже заполнен. Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS. Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю. Указатель целевого буфера имеет значение NULL или его длина равна нулю, но при этом присутствовала строка источника ненулевой длины.

Код возврата

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

Указан недопустимый флаг.
Значение в cchDest больше максимального размера буфера.
Целевой буфер уже заполнен.
Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS.
Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю.
Указатель целевого буфера имеет значение NULL или его длина равна нулю, но при этом присутствовала строка источника ненулевой длины.

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

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

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

Используйте RtlStringCchVPrintfExW для обработки строк Юникода и RtlStringCchVPrintfExA для обработки строк ANSI. Используемая форма зависит от ваших данных.

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

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

PszDest не может иметь значение NULL , если не установлен флаг STRSAFE_IGNORE_NULLS.

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

Требования

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

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

RtlStringCbVPrintfEx

RtlStringCchPrintfEx

RtlStringCchVPrintf

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