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

  • Статья

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

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

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

Синтаксис

STRSAFEAPI StringCbCatExA(
  [in, out]       STRSAFE_LPSTR  pszDest,
  [in]            size_t         cbDest,
  [in]            STRSAFE_LPCSTR pszSrc,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcbRemaining,
  [in]            DWORD          dwFlags
);

Параметры

[in, out] pszDest

Тип: LPTSTR

Строка, с которой должна быть сцеплена pszSrc , и которая получит всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest.

[in] cbDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

Исходная строка, сцепленная с концом pszDest. Эта строка должна заканчиваться null.

[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
 Если функция выполняется успешно, для заполнения неинициализированной части pszDest после завершающего символа NULL используется низкий байт dwFlags (0).
STRSAFE_IGNORE_NULLS
0x00000100
 Обрабатывать пустые строковые указатели null (TEXT("")). Этот флаг полезен для эмуляции таких функций, как lstrcpy.
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
 Если функция завершается сбоем, pszDest не будет тронут. К исходному содержимому ничего не добавляется.

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

Тип: HRESULT

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

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

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

Комментарии

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbCat

StringCbCatNEx

StringCchCatEx