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

Статья
05/03/2024

Функции RtlStringCbCatNExW и RtlStringCbCatNExA объединяют две строки с подсчетом байтов, ограничивая размер добавленной строки.

Синтаксис

NTSTRSAFEDDI RtlStringCbCatNExW(
  [in, out, optional] NTSTRSAFE_PWSTR pszDest,
  [in]                size_t          cbDest,
  [in, optional]      STRSAFE_PCNZWCH pszSrc,
                      size_t          cbToAppend,
  [out, optional]     NTSTRSAFE_PWSTR *ppszDestEnd,
  [out, optional]     size_t          *pcbRemaining,
  [in]                DWORD           dwFlags
);

Параметры

[in, out, optional] pszDest

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

[in] cbDest

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

Для строк Юникода максимальное число байтов NTSTRSAFE_MAX_CCH * sizeof(WCHAR)

Для строк ANSI максимальное число байтов NTSTRSAFE_MAX_CCH * sizeof(char)

Если pszDest имеет значение NULL, cbDest должен быть равен нулю.

[in, optional] pszSrc

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

cbToAppend

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

[out, optional] ppszDestEnd

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

[out, optional] pcbRemaining

Если вызывающий объект предоставляет указатель адреса, отличный от 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 в следующих случаях: Указан недопустимый флаг. Значение в cbDest больше максимального размера буфера. Целевой буфер уже заполнен. Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS . Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю. Указатель целевого буфера имеет значение NULL или его длина равна нулю, но при этом присутствовала строка источника ненулевой длины.

Код возврата

Описание

STATUS_SUCCESS

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

STATUS_BUFFER_OVERFLOW

Это состояние предупреждения означает, что операция копирования не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано, дополнительные сведения см. в параметре dwFlags .

STATUS_INVALID_PARAMETER

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

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

Указан недопустимый флаг.
Значение в cbDest больше максимального размера буфера.
Целевой буфер уже заполнен.
Существовал указатель NULL без флага STRSAFE_IGNORE_NULLS .
Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю.
Указатель целевого буфера имеет значение NULL или его длина равна нулю, но при этом присутствовала строка источника ненулевой длины.

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

Используйте RtlStringCbCatNExW для обработки строк Юникода и RtlStringCbCatNExA для обработки строк ANSI. Используемая форма зависит от данных, как показано в следующей таблице.

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

Если 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

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

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

Синтаксис

Параметры

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

Комментарии

Требования

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

Обратная связь

Обратная связь

Дополнительные ресурсы