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

Статья
02/29/2024

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

Синтаксис

NTSTRSAFEDDI RtlStringCbVPrintfExA(
  [out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]            size_t          cbDest,
  [out, optional] NTSTRSAFE_PSTR  *ppszDestEnd,
  [out, optional] size_t          *pcbRemaining,
  [in]            DWORD           dwFlags,
  [in, optional]  NTSTRSAFE_PCSTR pszFormat,
  [in]            va_list         argList
);

Параметры

[out, optional] pszDest

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

[in] cbDest

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

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

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

Если pszDest имеет значение NULL, cbDest должно быть равно нулю.

[out, optional] ppszDestEnd

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

[out, optional] pcbRemaining

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

[in] dwFlags

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

Значение	Значение
STRSAFE_FILL_BEHIND_NULL	Если задано и функция выполняется успешно, для заполнения части буфера назначения, следующей за завершающим символом NULL, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS	Если задано значение , pszDest , pszSrc или и то, и другое, может иметь значение NULL. Пустые указатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. Указатели 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 в следующих случаях: Указан недопустимый флаг. Значение в cbDest больше максимального размера буфера. Буфер назначения уже заполнен. Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS. Указатель буфера назначения имеет значение NULL, но размер буфера не равен нулю. Указатель буфера назначения имеет значение NULL или его длина равна нулю, но исходная строка ненулевой длины присутствует.

Код возврата

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

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

STATUS_INVALID_PARAMETER

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

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

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

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

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

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

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

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

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

Ни pszFormat , ни pszDest не могут иметь значение NULL , если не установлен флаг STRSAFE_IGNORE_NULLS. В этом случае оба значения могут иметь значение NULL. Если pszDest имеет значение NULL, pszFormat должен иметь значение NULL или указывать на пустую строку.

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

Требования

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

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

RtlStringCbPrintfEx

RtlStringCbVPrintf

RtlStringCchVPrintfEx