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

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

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

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

Syntax

STRSAFEAPI StringCchCatExA(
  [in, out]       STRSAFE_LPSTR  pszDest,
  [in]            size_t         cchDest,
  [in]            STRSAFE_LPCSTR pszSrc,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags
);

Parameters

[in, out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

[out, optional] ppszDestEnd

Тип: LPTSTR*

Адрес указателя на конец pszDest. Если ppszDestEnd не имеет значения NULL , а любые данные добавляются в целевой буфер, это указывает на завершающий символ NULL в конце строки.

[out, optional] pcchRemaining

Тип: size_t*

Число неиспользуемых символов в pszDest, включая завершающийся символ NULL. Если pcchRemaining имеет значение 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 для проверки возвращаемого значения этой функции.

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

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

Замечания

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

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

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

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

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

Note

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

Требования

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

См. также

Ссылки

StringCbCatEx

StringCchCat

StringCchCatNEx

  • Last updated on