Функция RtlStringCbCopyUnicodeStringEx (ntstrsafe.h)
Функция RtlStringCbCopyUnicodeStringEx копирует содержимое структуры UNICODE_STRING в указанное назначение.
Синтаксис
NTSTRSAFEDDI RtlStringCbCopyUnicodeStringEx(
[out] NTSTRSAFE_PWSTR pszDest,
[in] size_t cbDest,
[in] PCUNICODE_STRING SourceString,
[out] NTSTRSAFE_PWSTR *ppszDestEnd,
[out, optional] size_t *pcbRemaining,
[in] DWORD dwFlags
);
Параметры
[out] pszDest
Необязательный параметр. Указатель на буфер, получающий скопированную строку. Строка, на которую указывает структура UNICODE_STRING параметра SourceString, копируется в буфер в pszDest и завершается символом NULL. Этот указатель может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[in] cbDest
Размер целевого буфера (в байтах). Буфер должен быть достаточно большим для строки и завершающего символа NULL. Максимальное число байтов в буфере равно NTSTRSAFE_MAX_CCH * sizeof(WCHAR).
[in] SourceString
Необязательный элемент. Указатель на структуру UNICODE_STRING , содержащую копируемые строки. Максимальное число байтов в строке равно NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). Этот указатель может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[out] ppszDestEnd
Необязательный элемент. Если вызывающий объект предоставляет указатель адреса, отличный от NULL , то после завершения операции копирования функция загружает этот адрес с указателем на конечный символ конца строки NULL в буфере назначения.
[out, optional] pcbRemaining
Необязательный элемент. Если вызывающий объект предоставляет указатель на адрес, отличный от NULL , функция загружает адрес с количеством неиспользуемых байтов, которые находятся в буфере, на который указывает pszDest , включая байты, используемые для завершающего символа NULL.
[in] dwFlags
Один или несколько флагов и, при необходимости, байт заливки. Флаги определяются следующим образом:
| Значение | Значение |
|---|---|
| STRSAFE_FILL_BEHIND_NULL | Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за символом NULL, используется низкий байт dwFlags . |
| STRSAFE_IGNORE_NULLS | Если этот флаг установлен, указатель источника или назначения может иметь значение NULL. RtlStringCbCopyUnicodeStringEx обрабатывает указатели исходного буфера NULL как пустые строки (TEXT("")), которые можно скопировать. Указатели конечного буфера назначения NULL не могут получать непустые строки. |
| STRSAFE_FILL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags , а буфер завершается со значением NULL. Эта операция перезаписывает все уже существующее содержимое буфера. |
| STRSAFE_NULL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера. |
| STRSAFE_NO_TRUNCATION |
Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW:
|
Возвращаемое значение
RtlStringCbCopyUnicodeStringEx возвращает одно из следующих значений NTSTATUS.
| Код возврата | Описание |
|---|---|
| STATUS_SUCCESS | Это состояние успешного выполнения означает, что исходные данные присутствовали, строка была скопирована без усечения, а результирующий буфер назначения завершается null. |
| STATUS_BUFFER_OVERFLOW | Это состояние предупреждения означает, что операция копирования не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано в dwFlags, целевой буфер не изменяется. Если флаг не задан, целевой буфер содержит усеченную версию скопированной строки. |
| STATUS_INVALID_PARAMETER | Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем списке. |
RtlStringCbCopyUnicodeStringEx возвращает значение STATUS_INVALID_PARAMETER, если происходит одно из следующих действий:
- Недопустимое содержимое структуры UNICODE_STRING .
- Недопустимый флаг указан в dwFlags.
- Значение в cbDest больше максимального размера буфера.
- Буфер назначения (на который указывает pszDest ) уже заполнен.
- Указатель буфера имеет значение NULL , а флаг STRSAFE_IGNORE_NULLS не указан.
- Указатель целевого буфера имеет значение NULL, но размер буфера не равен нулю.
- Указатель целевого буфера имеет значение NULL или его длина равна нулю, но при этом присутствует исходная строка ненулевой длины.
Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.
Комментарии
Функция RtlStringCbCopyUnicodeStringEx использует размер буфера назначения (который указывает параметр cbDest ), чтобы операция копирования не записывалась за конец буфера.
RtlStringCbCopyUnicodeStringEx добавляет к функциям функции RtlStringCbCopyUnicodeStringString, возвращая указатель на конец конечной строки и количество байтов, оставшихся неиспользуемыми в этой строке. Вы можете передать флаги в функцию для дополнительного управления.
Если исходная и целевая строки перекрываются, поведение функции не определено.
Указатели *SourceString *и pszDest не могут иметь значение NULL , если флаг STRSAFE_IGNORE_NULLS не установлен в dwFlags. Если задано STRSAFE_IGNORE_NULLS, один или оба этих указателя могут иметь значение NULL. Если указатель pszDest имеет значение NULL, *SourceString *pointer должен иметь значение NULL или структура UNICODE_STRING должна описывать пустую строку.
Дополнительные сведения о безопасных строковых функциях см. в разделе Использование безопасных строковых функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Windows XP с пакетом обновления 1 (SP1) и более поздних версиях Windows. |
| Целевая платформа | Персональный компьютер |
| Верхняя часть | ntstrsafe.h (включая Ntstrsafe.h) |
| Библиотека | Ntstrsafe.lib |
| IRQL | Любое значение, если строки, которыми осуществляется управление, всегда находятся в памяти, в противном случае PASSIVE_LEVEL |