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


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

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

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

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

Синтаксис

STRSAFEAPI StringCbCatNExA(
  [in, out]       STRSAFE_LPSTR  pszDest,
  [in]            size_t         cbDest,
  [in]            STRSAFE_PCNZCH pszSrc,
  [in]            size_t         cbToAppend,
  [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.

[in] cbToAppend

Тип: size_t

Максимальное число байтов, добавляемых к pszDest.

[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
Если функция завершается сбоем, pszDest нетронуто. К исходному содержимому ничего не добавляется.

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

Тип: HRESULT

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

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

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

Комментарии

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbCatEx

StringCbCatN

StringCchCatNEx