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

Статья
11/20/2024

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

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. Если pcbRemainingnull, счетчик не сохраняется или возвращается.

[in] dwFlags

Тип: DWORD

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP с пакетом обновления 2 (SP2) [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 с пакетом обновления 1 (SP1) [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	strsafe.h

См. также

Справочник

StringCbCatEx

StringCbCatN

StringCchCatNEx

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