Функция StringCbVPrintfW (strsafe.h)

  • Статья

Записывает отформатированные данные в указанную строку, используя указатель на список аргументов. Размер целевого буфера предоставляется функции, чтобы гарантировать, что она не записывает данные после конца этого буфера.

StringCbVPrintf является заменой следующих функций:

Синтаксис

STRSAFEAPI StringCbVPrintfW(
  [out] STRSAFE_LPWSTR  pszDest,
  [in]  size_t          cbDest,
  [in]  STRSAFE_LPCWSTR pszFormat,
  [in]  va_list         argList
);

Параметры

[out] pszDest

Тип: LPTSTR

Буфер назначения, который получает отформатированную строку, завершающуюся значением NULL, созданную из pszFormat и argList.

[in] cbDest

Тип: size_t

Размер целевого буфера в байтах. Это значение должно быть достаточно большим, чтобы вместить итоговую отформатированную строку и завершающий символ NULL. Максимально допустимое количество байтов — STRSAFE_MAX_CCH * sizeof(TCHAR).

[in] pszFormat

Тип: LPCTSTR

Строка формата. Эта строка должна заканчиваться null. Дополнительные сведения см. в разделе Синтаксис спецификации формата.

[in] argList

Тип: va_list

Аргументы, которые необходимо вставить в строку pszFormat .

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

Тип: HRESULT

Эта функция может возвращать одно из следующих значений. Настоятельно рекомендуется использовать макросы SUCCEEDED и FAILED для проверки возвращаемого значения этой функции.

Код возврата Описание
S_OK
 Достаточно места для копирования результата в pszDest без усечения, а буфер завершается null.
STRSAFE_E_INVALID_PARAMETER
 Значение в cbDest равно 0 или больше .STRSAFE_MAX_CCH * sizeof(TCHAR)
STRSAFE_E_INSUFFICIENT_BUFFER
 Операция копирования завершилась сбоем из-за недостаточного пространства в буфере. Целевой буфер содержит усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение приемлемо, это не обязательно может рассматриваться как условие сбоя.
 

Обратите внимание, что эта функция возвращает значение HRESULT , в отличие от функций, которые она заменяет.

Комментарии

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

Дополнительные сведения о va_lists см. в соглашениях, определенных в Stdarg.h.

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

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

StringCbVPrintf можно использовать в универсальной форме или в более конкретных формах. Тип данных строки определяет форму этой функции, которую следует использовать, как показано в следующей таблице.

Тип данных String Строковый литерал Функция
char Строка StringCbVPrintfA
TCHAR TEXT("string") StringCbVPrintf
WCHAR L"string" StringCbVPrintfW
 

Примечание

Заголовок strsafe.h определяет StringCbVPrintf в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP с пакетом обновления 2 (SP2) [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения | Приложения UWP]
Целевая платформа Windows
Header strsafe.h

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

Справочные материалы

StringCbPrintf

StringCbVPrintfEx

StringCchVPrintf