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

Функция RtlUnicodeStringCbCatStringNEx объединяет две строки, если целевая строка содержится в структуре UNICODE_STRING , ограничивая размер добавленной строки.

Синтаксис

NTSTRSAFEDDI RtlUnicodeStringCbCatStringNEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            NTSTRSAFE_PCWSTR pszSrc,
  [in]            size_t           cbToAppend,
  [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.

[in] cbToAppend

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

[out, optional] RemainingString

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

[in] dwFlags

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

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

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

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

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

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

Замечания

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

RtlUnicodeStringCbCatStringNEx добавляет к функциям функции функции RtlUnicodeStringCbCatStringN , возвращая UNICODE_STRING структуру , которая определяет конец конечной строки и количество байтов, которые остаются неиспользуемыми в этой строке. Вы можете передать флаги в RtlUnicodeStringCbCatStringNEx для дополнительного элемента управления.

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

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

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

Требования

См. также

• RtlUnicodeStringCbCatStringN
• RtlUnicodeStringCchCatStringNEx
• UNICODE_STRING