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

  • Статья

Функция RtlUnicodeStringCatStringEx объединяет две строки, если конечная строка содержится в структуре UNICODE_STRING .

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCatStringEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            NTSTRSAFE_PCWSTR pszSrc,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags
);

Параметры

[in, out] DestinationString

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

[in] pszSrc

Необязательный элемент. Предоставленный вызывающим элементом указатель на исходную строку, завершаемую null. Эта строка будет сцеплена с концом строки, содержащейся в структуре UNICODE_STRING , указанной DestinationString . PszSrc может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.

[out, optional] RemainingString

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

[in] dwFlags

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

Значение Значение
STRSAFE_FILL_BEHIND Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за последним символом в строке, используется низкий байт dwFlags .
STRSAFE_IGNORE_NULLS Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за последним символом в строке, используется низкий байт dwFlags .
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, длина строки назначения будет равна нулю байтов.

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

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

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

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

  • Недопустимое содержимое структуры UNICODE_STRING .
  • Недопустимый флаг указан в dwFlags.
  • Буфер назначения уже заполнен.
  • Указатель буфера имеет значение NULL , а флаг STRSAFE_IGNORE_NULLS не указан в dwFlags.
  • Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю.
  • Указатель конечного буфера имеет значение NULL или его длина равна нулю, но при этом присутствует строка источника ненулевой длины.

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

Комментарии

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

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

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

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

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

Требования

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

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