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