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

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

  • Статья

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

Синтаксис

NTSTRSAFEDDI RtlStringCbPrintfExW(
  [out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cbDest,
  [out, optional] NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcbRemaining,
  [in]            DWORD            dwFlags,
  [in, optional]  NTSTRSAFE_PCWSTR pszFormat,
                  ...              
);

Параметры

[out, optional] pszDest

Указатель на буфер, предоставленный вызывающим объектом, который получает отформатированную строку, завершающуюся значением NULL. Функция создает эту строку как из строки форматирования, предоставленной pszFormat , так и из списка аргументов функции. Указатель 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.

...

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

Комментарии

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

  • sprintf
  • swprintf
  • _snprintf
  • _snwprintf
Все эти функции принимают строку формата и список аргументов, интерпретируют их и создают форматированную строку. Размер целевого буфера в байтах предоставляется для RtlStringCbPrintfExW и RtlStringCbPrintfExA , чтобы гарантировать, что они не записываются после конца буфера.

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

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

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

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

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

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

Требования

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

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

RtlStringCbVPrintfEx

RtlStringCchPrintf

RtlStringCchPrintfEx