Функция RtlStringCchCatExW (ntstrsafe.h)

  • Статья

Функции RtlStringCchCatExW и RtlStringCchCatExA объединяют две строки с подсчетом символов.

Синтаксис

NTSTRSAFEDDI RtlStringCchCatExW(
  [in, out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]                size_t           cchDest,
  [in]                NTSTRSAFE_PCWSTR pszSrc,
  [out, optional]     NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional]     size_t           *pcchRemaining,
  [in]                DWORD            dwFlags
);

Параметры

[in, out, optional] pszDest

Указатель на буфер, который на входных данных содержит строку, завершающуюся нулевым значением, с которой будет сцеплен pszSrc . В выходных данных это буфер назначения, содержащий всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest и заканчивается символом NULL. Указатель pszDest может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[in] cchDest

Размер буфера назначения в символах. Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH. Если pszDest имеет значение NULL, cchDest должен быть равен нулю.

[in] pszSrc

Указатель на строку, завершаемую нулевым значением. Эта строка будет сцеплена с концом строки, содержащейся в буфере в pszDest. Указатель pszSrc может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

Один или несколько флагов и, при необходимости, байт заполнения. Флаги определяются следующим образом:

Значение Значение
STRSAFE_FILL_BEHIND_NULL Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за завершающим символом NULL, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS Если этот флаг установлен, pszDest , pszSrc или оба значения могут иметь значение NULL. Пустые указатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. Указатели NULLpszDest не могут получать непустые строки.
STRSAFE_FILL_ON_FAILURE Если этот флаг установлен и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags , а буфер завершается значением NULL. Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NULL_ON_FAILURE Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NO_TRUNCATION

Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW:

  • Если также указан STRSAFE_FILL_ON_FAILURE , STRSAFE_NO_TRUNCATION соответствующим образом заполняет буфер назначения.
  • В противном случае целевой буфер будет не изменен.

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

Функция возвращает одно из значений NTSTATUS, перечисленных в следующей таблице. Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.

Код возврата Описание
STATUS_SUCCESS Это состояние успешного выполнения означает, что исходные данные присутствуют, выходная строка была создана без усечения, а результирующий буфер назначения завершается null.
STATUS_BUFFER_OVERFLOW Это состояние предупреждения означает, что операция не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано, дополнительные сведения см. в параметре dwFlags .
STATUS_INVALID_PARAMETER

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

Функция возвращает значение STATUS_INVALID_PARAMETER в следующих случаях:

  • Указан недопустимый флаг.
  • Значение в cchDest больше максимального размера буфера.
  • Буфер назначения уже заполнен.
  • Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS .
  • Указатель буфера назначения имеет значение NULL, но размер буфера не равен нулю.
  • Указатель буфера назначения имеет значение NULL или его длина равна нулю, но исходная строка ненулевой длины присутствует.

Комментарии

Вместо следующих функций следует использовать RtlStringCchCatExW и RtlStringCchCatExA:

  • strcat
  • wcscat

Размер буфера назначения указан в символах, чтобы гарантировать, что RtlStringCchCatExW и RtlStringCchCatExA не записываются за конец буфера.

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

Используйте RtlStringCchCatExW для обработки строк Юникода и RtlStringCchCatExA для обработки строк ANSI. Используемая форма зависит от ваших данных.

Строковый тип данных Строковый литерал Функция
WCHAR L"string" RtlStringCchCatExW
char Строка RtlStringCchCatExA

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

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

Дополнительные сведения о функциях безопасных строк см. в разделе Использование безопасных строковых функций.

Требования

Требование Значение
Минимальная версия клиента Доступно в Windows XP с пакетом обновления 1 (SP1) и более поздних версиях Windows.
Целевая платформа Персональный компьютер
Верхняя часть ntstrsafe.h (включая Ntstrsafe.h)
Библиотека Ntstrsafe.lib
IRQL Любой, если строки, которыми осуществляется управление, всегда находятся в памяти, в противном случае PASSIVE_LEVEL

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