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

  • Статья

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

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

StringCchCatNEx заменяет следующие функции:

Синтаксис

STRSAFEAPI StringCchCatNExW(
  [in, out]       STRSAFE_LPWSTR  pszDest,
  [in]            size_t          cchDest,
  [in]            STRSAFE_PCNZWCH pszSrc,
  [in]            size_t          cchToAppend,
  [out, optional] STRSAFE_LPWSTR  *ppszDestEnd,
  [out, optional] size_t          *pcchRemaining,
  [in]            DWORD           dwFlags
);

Параметры

[in, out] pszDest

Тип: LPTSTR

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

[in] cchDest

Тип: size_t

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

[in] pszSrc

Тип: LPCTSTR

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

[in] cchToAppend

Тип: size_t

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

[out, optional] ppszDestEnd

Тип: LPTSTR*

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

[out, optional] pcchRemaining

Тип: size_t*

Количество неиспользуемых символов в pszDest, включая завершающий пустой символ. Если pcchRemaining имеет значение 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
 Значение в cchDest больше STRSAFE_MAX_CCH, был передан недопустимый флаг или имеются расхождения между размером pszDest, cchDest и объемом добавляемого материала в pszSrc.
STRSAFE_E_INSUFFICIENT_BUFFER
 Операция копирования завершилась сбоем из-за нехватки места в буфере. В зависимости от значения dwFlags, буфер назначения может содержать усеченную версию предполагаемого результата, завершаемую null. В ситуациях, когда усечение является приемлемым, это не обязательно может рассматриваться как условие сбоя.
 

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

Комментарии

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

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

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

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

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

Примечание

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

Требования

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

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

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

StringCbCatNEx

StringCchCatEx

StringCchCatN