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

Статья
11/20/2024

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

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

Синтаксис

STRSAFEAPI StringCbCatW(
  [in, out] STRSAFE_LPWSTR  pszDest,
  [in]      size_t          cbDest,
  [in]      STRSAFE_LPCWSTR pszSrc
);

Параметры

[in, out] pszDest

Тип: LPTSTR

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

[in] cbDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

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

Тип: HRESULT

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

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

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

Замечания

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

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

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

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

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

Заметка

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

Требования

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

См. также

Справочник

StringCbCatEx

StringCbCatN

StringCchCat

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