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