Функция RtlStringCchCopyNExW (ntstrsafe.h)
Функции RtlStringCchCopyNExW и RtlStringCchCopyNExA копируют строку с подсчетом символов в буфер, ограничивая размер скопированной строки.
Синтаксис
NTSTRSAFEDDI RtlStringCchCopyNExW(
[out, optional] NTSTRSAFE_PWSTR pszDest,
[in] size_t cchDest,
[in, optional] STRSAFE_PCNZWCH pszSrc,
size_t cchToCopy,
[out, optional] NTSTRSAFE_PWSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags
);
Параметры
[out, optional] pszDest
Указатель на буфер, предоставленный вызывающим объектом, который получает скопированную строку. Строка в pszSrc копируется в буфер в pszDest и завершается символом NULL. Указатель pszDest может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[in] cchDest
Размер целевого буфера (в символах). Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH. Если pszDest имеет значение NULL, параметр cchDest должен быть равен нулю.
[in, optional] pszSrc
Указатель на строку, предоставляемую вызывающим, завершаемую null.
cchToCopy
Максимальное количество символов для копирования из *pszSrc* в буфер, предоставленный *pszDest*.
[out, optional] ppszDestEnd
Если вызывающий объект предоставляет указатель адреса, отличный от NULL , то после завершения операции копирования функция загружает этот адрес с указателем на конечный символ конца строки null буфера назначения.
[out, optional] pcchRemaining
Если вызывающий объект предоставляет указатель адреса, отличный от NULL , функция загружает адрес с количеством неиспользуемых символов, которые находятся в буфере, на который указывает pszDest, включая завершающий символ NULL.
[in] dwFlags
Один или несколько флагов и, при необходимости, байт заливки. Флаги определяются следующим образом:
Значение | Значение |
---|---|
STRSAFE_FILL_BEHIND_NULL | Если этот флаг установлен и функция выполняется успешно, для заполнения части буфера назначения, следующей за символом NULL, используется низкий байт dwFlags . |
STRSAFE_IGNORE_NULLS | Если этот флаг установлен, pszDest , pszSrc или и то, и другое может иметь значение NULL. Пустые указатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. Указатели nullpszDest не могут получать непустые строки. |
STRSAFE_FILL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для заполнения всего целевого буфера используется низкий байт dwFlags , а буфер завершается со значением NULL. Эта операция перезаписывает все уже существующее содержимое буфера. |
STRSAFE_NULL_ON_FAILURE | Если этот флаг установлен и функция завершается сбоем, для буфера назначения устанавливается пустая строка (TEXT("")). Эта операция перезаписывает все уже существующее содержимое буфера. |
STRSAFE_NO_TRUNCATION |
Если этот флаг установлен и функция возвращает STATUS_BUFFER_OVERFLOW:
|
Возвращаемое значение
Функция возвращает одно из значений NTSTATUS, перечисленных в следующей таблице. Сведения о проверке значений NTSTATUS см. в разделе Использование значений NTSTATUS.
Код возврата | Описание |
---|---|
STATUS_SUCCESS | Это состояние успешного выполнения означает, что исходные данные присутствовали, строка была скопирована без усечения, а результирующий буфер назначения завершается null. |
STATUS_BUFFER_OVERFLOW | Это состояние предупреждения означает, что операция копирования не завершена из-за нехватки места в буфере назначения. Если STRSAFE_NO_TRUNCATION задано в dwFlags, дополнительные сведения см. в параметре dwFlags . |
STATUS_INVALID_PARAMETER |
Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает значение STATUS_INVALID_PARAMETER в следующих случаях:
|
Комментарии
Вместо strncpy следует использовать RtlStringCchCopyNExW и RtlStringCchCopyNExA. Функции копируют заданное количество символов из исходной строки. Размер целевого буфера в символах предоставляется для RtlStringCchCopyNExW и RtlStringCchCopyNExA , чтобы гарантировать, что они не записываются после конца буфера.
Обратите внимание, что эти функции ведут себя иначе, чем strncpy в одном отношении. Если cchSrc больше, чем число символов в pszSrc, RtlStringCchCopyNExW и RtlStringCchCopyNExA, в отличие от strncpy, не продолжайте заполнять pszDest символами NULL до тех пор, пока не будут скопированы символы cchSrc .
RtlStringCchCopyNExW и RtlStringCchCopyNExA добавляют к функциональным возможностям RtlStringCchCopyN , возвращая указатель на конец строки назначения, а также количество символов, оставшихся неиспользуемыми в этой строке. Флаги можно передать в функцию для дополнительного управления.
Используйте RtlStringCchCopyNExW для обработки строк Юникода и RtlStringCchCopyNExA для обработки строк ANSI. Используемая форма зависит от данных, как показано в следующей таблице.
Строковый тип данных | Строковый литерал | Функция |
---|---|---|
WCHAR | L"string" | RtlStringCchCopyNExW |
char | Строка | RtlStringCchCopyNExA |
Если pszSrc и pszDest указывают на перекрывающиеся строки, поведение функции не определено.
Ни pszSrc, ни pszDest не могут иметь значение NULL , если не установлен флаг STRSAFE_IGNORE_NULLS, и в этом случае любой из них может иметь значение NULL. Если pszDest имеет значение NULL, pszSrc должен иметь значение NULL или указывать на пустую строку.
Дополнительные сведения о безопасных строковых функциях см. в разделе Использование безопасных строковых функций.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Доступно в Windows XP с пакетом обновления 1 (SP1) и более поздних версиях Windows. |
Целевая платформа | Персональный компьютер |
Верхняя часть | ntstrsafe.h (включая Ntstrsafe.h) |
Библиотека | Ntstrsafe.lib |
IRQL | Любое значение, если строки, которыми осуществляется управление, всегда находятся в памяти, в противном случае PASSIVE_LEVEL |
См. также раздел
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по