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

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

  • Статья

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

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

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

Синтаксис

STRSAFEAPI StringCbPrintfExA(
  [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,
                  ...            
);

Параметры

[out] pszDest

Тип: LPTSTR

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

[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

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

Значение Значение
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

Тип: LPCTSTR

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

...

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

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

Тип: HRESULT

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

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

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

Комментарии

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbVPrintfEx

StringCchPrintf

StringCchPrintfEx