Функция RtlUnicodeStringCbCopyNEx (ntstrsafe.h)
Функция RtlUnicodeStringCbCopyNEx копирует строку из одной структуры UNICODE_STRING в другую, ограничивая размер скопированной строки.
Синтаксис
NTSTRSAFEDDI RtlUnicodeStringCbCopyNEx(
[out] PUNICODE_STRING DestinationString,
[in] PCUNICODE_STRING SourceString,
[in] size_t cbToCopy,
[out, optional] PUNICODE_STRING RemainingString,
[in] DWORD dwFlags
);
Параметры
[out] DestinationString
Необязательный параметр. Указатель на структуру UNICODE_STRING , получающую скопированную строку. Строка, на которую указывает структура UNICODE_STRING параметра SourceString, копируется в буфер, на который указывает структура UNICODE_STRING параметра DestinationString. Максимальное число байтов в буфере строк структуры DestinationString равно 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] cbToCopy
Число байтов, копируемых из источника в место назначения.
[out, optional] RemainingString
Необязательный элемент. Если вызывающий объект предоставляет указатель, отличный от NULL , на структуру UNICODE_STRING , функция присваивает члену buffer этой структуры конец сцепленной строки, элемент Length структуры — нулю, а член MaximumLength структуры — число байтов, оставшихся в целевом буфере. Параметр RemainingString может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[in] dwFlags
Один или несколько флагов и, при необходимости, байт заливки. Флаги определяются следующим образом:
| Значение | Значение |
|---|---|
| STRSAFE_FILL_BEHIND_NULL | Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за последним символом в строке, используется низкий байт dwFlags . |
| STRSAFE_IGNORE_NULLS | Если этот флаг установлен, указатель источника или назначения или и то, и другое может иметь значение NULL. RtlUnicodeStringCbCopyNEx обрабатывает указатели исходного буфера NULL как пустые строки (TEXT("")), которые можно скопировать. Указатели конечного буфера назначения NULL не могут получать непустые строки. |
| STRSAFE_FILL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags . Эта операция перезаписывает все уже существующее содержимое буфера. |
| STRSAFE_NULL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера. |
| STRSAFE_NO_TRUNCATION |
Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW:
|
| STRSAFE_ZERO_LENGTH_ON_FAILURE | Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW, длина строки назначения будет равна нулю байтов. |
Возвращаемое значение
RtlUnicodeStringCbCopyNEx возвращает одно из следующих значений NTSTATUS.
| Код возврата | Описание |
|---|---|
| STATUS_SUCCESS | Это состояние успешного выполнения означает наличие исходных данных, а строки были сцеплены без усечения. |
| STATUS_BUFFER_OVERFLOW | Это состояние предупреждения означает, что операция копирования не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано в dwFlags, целевой буфер не изменяется. Если флаг не задан, целевой буфер содержит усеченную версию скопированной строки. |
| STATUS_INVALID_PARAMETER | Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем списке. |
RtlUnicodeStringCbCopyNEx возвращает значение STATUS_INVALID_PARAMETER при выполнении одного из следующих действий:
- Недопустимое содержимое структуры UNICODE_STRING .
- Недопустимый флаг указан в dwFlags.
- Буфер назначения уже заполнен.
- Указатель буфера имеет значение NULL , а флаг STRSAFE_IGNORE_NULLS не указан в dwFlags.
- Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю.
- Указатель конечного буфера имеет значение NULL или его длина равна нулю, но при этом присутствует строка источника ненулевой длины.
- Значение параметра cbToCopy больше NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).
Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.
Комментарии
Функция RtlUnicodeStringCbCopyNEx использует размер буфера назначения для обеспечения того, чтобы операция копирования не записыла данные за конец буфера. По умолчанию функция не завершает результирующую строку значением NULL (т. е. нулем). В качестве параметра вызывающий объект может использовать флаг STRSAFE_FILL_BEHIND и значение байта заливки, равное нулю, чтобы завершить результирующую строку, которая не занимает весь буфер назначения.
RtlUnicodeStringCbCopyNEx добавляет к функциональным возможностям функции RtlUnicodeStringCbCopyN , возвращая структуру UNICODE_STRING , которая идентифицирует конец строки назначения и количество байтов, оставшихся неиспользуемыми в этой строке. Для дополнительного управления можно передать флаги в RtlUnicodeStringCbCopyNEx .
Если исходная и целевая строки перекрываются, поведение функции не определено.
Указатели 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по