функция StringCbVPrintf_lExA (strsafe.h)

  • Статья

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

StringCbVPrintf_lEx похожа на StringCbVPrintfEx , но включает параметр для сведений о языковом стандарте.

Синтаксис

STRSAFEAPI StringCbVPrintf_lExA(
  [out]           STRSAFE_LPSTR                                  pszDest,
  [in]            size_t                                         cbDest,
  [out]           STRSAFE_LPSTR                                  *ppszDestEnd,
  [out, optional] size_t                                         *pcbRemaining,
  [in]            DWORD                                          dwFlags,
  [in]            _Printf_format_string_params_(2)STRSAFE_LPCSTR pszFormat,
  [in]            _locale_t                                      locale,
  [in]            va_list                                        argList
);

Параметры

[out] pszDest

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

[in] cbDest

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

[out] ppszDestEnd

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

[out, optional] pcbRemaining

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

[in] dwFlags

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

Значение Значение
STRSAFE_FILL_BEHIND_NULL
0x00000200
 Если функция выполняется успешно, низкий байт dwFlags (0) используется для заполнения неинициализированной части pszDest после завершающего символа NULL.
STRSAFE_IGNORE_NULLS
0x00000100
 Обрабатываются пустые строки указателей NULL (TEXT("")).
STRSAFE_FILL_ON_FAILURE
0x00000400
 Если функция завершается ошибкой, для заполнения всего буфера pszDest используется низкий байт dwFlags (0), а буфер завершается значением NULL. В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая возвращаемая усеченная строка перезаписывается.
STRSAFE_NULL_ON_FAILURE
0x00000800
 Если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается.
STRSAFE_NO_TRUNCATION
0x00001000
 Как и в случае STRSAFE_NULL_ON_FAILURE, если функция завершается сбоем, pszDest получает пустую строку (TEXT("")). В случае сбоя STRSAFE_E_INSUFFICIENT_BUFFER любая усеченная строка перезаписывается.

[in] pszFormat

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

[in] locale

Объект языкового стандарта. Дополнительные сведения см. в разделе _create_locale.

[in] argList

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

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

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

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

Комментарии

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

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

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

Чтобы использовать эту функцию, необходимо определить следующий макрос в файле заголовка перед включением StrSafe.h.

#define STRSAFE_LOCALE_FUNCTIONS

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows Vista [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header strsafe.h