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

  • Статья

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

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

Синтаксис

STRSAFEAPI StringCbCatNA(
  [in, out] STRSAFE_LPSTR  pszDest,
  [in]      size_t         cbDest,
  [in]      STRSAFE_PCNZCH pszSrc,
  [in]      size_t         cbToAppend
);

Параметры

[in, out] pszDest

Тип: LPTSTR

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

[in] cbDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

[in] cbToAppend

Тип: size_t

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

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

Тип: HRESULT

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

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

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

Комментарии

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

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

Ни pszSrc, ни pszDest не должны иметь значение NULL. См. раздел StringCbCatNEx , если требуется обработка значений нулевого строкового указателя.

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

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

Примечание

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

Требования

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

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

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

StringCbCat

StringCbCatNEx

StringCchCatN