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

Функция RtlUnicodeStringCchCopyStringNEx копирует строку в структуру UNICODE_STRING при ограничении размера скопированной строки.

Синтаксис

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

Параметры

[out] DestinationString

Необязательно. Указатель на структуру UNICODE_STRING , которая получает скопированную строку. Строка, на которую указывает параметр pszSrc (за исключением конца null), копируется в буфер, на который указывает UNICODE_STRING структура параметраDestinationString. Максимальное число символов в строке равно NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS заданы в dwFlags.

[in] pszSrc

Необязательно. Указатель на строку для копирования. Этот указатель может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS заданы в dwFlags.

[in] cchToCopy

Количество символов, скопированных из источника в место назначения.

[out, optional] RemainingString

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

[in] dwFlags

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

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

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

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

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

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

Замечания

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

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

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

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

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

Требования

См. также

• RtlUnicodeStringCbCopyStringNEx
• RtlUnicodeStringCchCopyStringN
• UNICODE_STRING