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

  • Статья

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

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

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

Синтаксис

STRSAFEAPI StringCchPrintfExA(
  [out]           STRSAFE_LPSTR  pszDest,
  [in]            size_t         cchDest,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags,
  [in]            STRSAFE_LPCSTR pszFormat,
                  ...            
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[out, optional] ppszDestEnd

Тип: LPTSTR*

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

[out, optional] pcchRemaining

Тип: size_t*

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

[in] dwFlags

Тип: DWORD

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

Значение Значение
STRSAFE_FILL_BEHIND_NULL
0x00000200
 Если функция выполняется успешно, для заполнения неинициализированной части pszDest после завершающего символа NULL используется низкий байт dwFlags (0).
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

Тип: LPCTSTR

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

...

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

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

Тип: HRESULT

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

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

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

Комментарии

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbPrintfEx

StringCchPrintf

StringCchVPrintfEx