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

Статья
08/07/2023

Функция RtlUnicodeStringCbCatNEx объединяет две строки, содержащиеся в UNICODE_STRING структурах, при этом ограничивает размер скопированной строки.

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCbCatNEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            PCUNICODE_STRING SourceString,
  [in]            size_t           cbToAppend,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags
);

Параметры

[in, out] DestinationString

Необязательный параметр. Указатель на структуру UNICODE_STRING . Эта структура включает буфер, который на входных данных содержит конечную строку, с которой будет сцеплена исходная строка. На выходе этот буфер является целевым буфером, который содержит всю результирующую строку. Исходная строка добавляется в конец строки назначения. Максимальное число байтов в строковом буфере структуры равно NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). DestinationString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[in] SourceString

Необязательный элемент. Указатель на структуру UNICODE_STRING . Эта структура включает буфер, содержащий исходную строку. Эта строка будет добавлена в конец строки назначения. Максимальное число байтов в строковом буфере структуры равно NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). SourceString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[in] cbToAppend

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

[out, optional] RemainingString

Необязательный элемент. Если вызывающий объект предоставляет на структуру UNICODE_STRING указатель, отличный от NULL, функция устанавливает элемент Buffer этой структуры в конец сцепленной строки, задает элемент Length структуры равным нулю, а член MaximumLength структуры задает количество байтов, оставшихся в буфере назначения. Параметр RemainingString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[in] dwFlags

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

Значение	Значение
STRSAFE_FILL_BEHIND	Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за последним символом в строке, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS	Если этот флаг установлен, указатель источника или назначения или и то, и другое может иметь значение NULL. RtlUnicodeStringCbCatNEx обрабатывает указатели исходного буфера NULL как пустые строки (TEXT("")), которые можно скопировать. Указатели буфера назначения NULL не могут получать непустые строки.
STRSAFE_FILL_ON_FAILURE	Если этот флаг установлен и функция завершается сбоем, для заполнения всего буфера назначения используется низкий байт dwFlags . Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NULL_ON_FAILURE	Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера.
STRSAFE_NO_TRUNCATION	Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW: Если также указан STRSAFE_FILL_ON_FAILURE , STRSAFE_NO_TRUNCATION соответствующим образом заполняет буфер назначения. В противном случае целевой буфер будет не изменен.
STRSAFE_ZERO_LENGTH_ON_FAILURE	Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW, длина строки назначения устанавливается равным нулю байтов.

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

RtlUnicodeStringCbCatNEx возвращает одно из следующих значений NTSTATUS.

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

RtlUnicodeStringCbCatNEx возвращает значение STATUS_INVALID_PARAMETER, когда происходит одно из следующих действий:

Содержимое структуры UNICODE_STRING недопустимо.
В dwFlags указан недопустимый флаг.
Буфер назначения уже заполнен.
Указатель буфера имеет значение NULL , а флаг STRSAFE_IGNORE_NULLS не указан в dwFlags.
Указатель буфера назначения имеет значение NULL, но размер буфера не равен нулю.
Указатель буфера назначения имеет значение NULL или его длина равна нулю, но присутствует строка источника ненулевой длины.
Значение параметра cbToAppend больше NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).

Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.

Функция RtlUnicodeStringCbCatNEx использует размер буфера назначения, чтобы гарантировать, что операция объединения не записывает данные после конца буфера. По умолчанию функция не завершает результирующую строку значением null (т. е. нулевым). В качестве варианта вызывающий объект может использовать флаг STRSAFE_FILL_BEHIND и значение байта байта заполнения, равное нулю, чтобы завершить результирующую строку, которая не занимает весь буфер назначения.

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

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

Указатели SourceString и DestinationString не могут иметь значение NULL, если флаг STRSAFE_IGNORE_NULLS не установлен в dwFlags. Если задано STRSAFE_IGNORE_NULLS, один или оба из этих указателей могут иметь значение NULL. Если указатель DestinationString имеет значение NULL, то указатель SourceString должен иметь значение NULL или структура UNICODE_STRING должна указывать пустую строку.

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

Требования

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

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

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

Синтаксис

Параметры

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

Комментарии

Требования

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

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

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