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