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

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

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

StringCbVPrintfEx заменяет следующие функции:

• vsprintf, vswprintf, _vstprintf
• vsnprintf, _vsnwprintf, _vsntprintf
• wvsprintf
• wvnsprintf

Синтаксис

STRSAFEAPI StringCbVPrintfExA(
  [out]           STRSAFE_LPSTR  pszDest,
  [in]            size_t         cbDest,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcbRemaining,
  [in]            DWORD          dwFlags,
  [in]            STRSAFE_LPCSTR pszFormat,
  [in]            va_list        argList
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[in] cbDest

Тип: size_t

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

[out, optional] ppszDestEnd

Тип: LPTSTR*

Адрес указателя на конец pszDest. Если параметр ppszDestEnd не равен NULL и какие-либо данные копируются в буфер назначения, это указывает на завершающий символ NULL в конце строки.

[out, optional] pcbRemaining

Тип: size_t*

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

[in] dwFlags

Тип: DWORD

Одно или несколько из следующих значений.

[in] pszFormat

Тип: LPCTSTR

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

[in] argList

Тип: va_list

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

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

Тип: HRESULT

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

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

Комментарии

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

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

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

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

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

Требования

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

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

StringCbPrintfEx

StringCbVPrintf

StringCchVPrintfEx