Функция RtlStringCbCatExW (ntstrsafe.h)
Функции RtlStringCbCatExW и RtlStringCbCatExA объединяют две строки с подсчетом байтов.
Синтаксис
NTSTRSAFEDDI RtlStringCbCatExW(
[in, out, optional] NTSTRSAFE_PWSTR pszDest,
[in] size_t cbDest,
[in, optional] NTSTRSAFE_PCWSTR pszSrc,
[out, optional] NTSTRSAFE_PWSTR *ppszDestEnd,
[out, optional] size_t *pcbRemaining,
[in] DWORD dwFlags
);
Параметры
[in, out, optional] pszDest
Указатель на буфер, который на входных данных содержит строку, завершающуюся нулевым значением, с которой будет сцеплен pszSrc . В выходных данных это буфер назначения, содержащий всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest и заканчивается символом NULL. Указатель pszDest может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[in] cbDest
Размер буфера назначения в байтах. Буфер должен быть достаточно большим, чтобы включать как строки, так и завершающий символ NULL.
Для строк Юникода максимальное число байтов NTSTRSAFE_MAX_CCH * sizeof(WCHAR)
Для строк ANSI максимальное число байтов NTSTRSAFE_MAX_CCH * sizeof(char)
[in, optional] pszSrc
Указатель на строку, завершаемую нулевым значением. Эта строка будет сцеплена с концом строки, содержащейся в буфере в pszDest. Указатель pszSrc может иметь значение NULL, но только если STRSAFE_IGNORE_NULLS задано в dwFlags.
[out, optional] ppszDestEnd
Если вызывающий объект предоставляет указатель адреса, отличный от NULL , то после завершения операции объединения функция загружает этот адрес с указателем на результирующий признак конца строки NULL буфера назначения.
[out, optional] pcbRemaining
Если вызывающий объект предоставляет указатель адреса, отличный от 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 . |
| STATUS_INVALID_PARAMETER |
Это состояние ошибки означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце. Функция возвращает STATUS_INVALID_PARAMETER в следующих случаях:
|
Комментарии
Вместо следующих функций следует использовать RtlStringCbCatExW и RtlStringCbCatExA.
- strcat
- wcscat
Так как RtlStringCbCatExW и RtlStringCbCatExAполучают размер буфера назначения в качестве входных данных, они не будут записывать данные за конец буфера.
RtlStringCbCatEx добавляет к функциональным возможностям RtlStringCbCat , возвращая указатель на конец строки назначения, а также количество байтов, оставшихся в этой строке. Флаги также можно передать в функцию для дополнительного управления.
Используйте RtlStringCbCatExW для обработки строк Юникода и RtlStringCbCatExA для обработки строк ANSI. Используемая форма определяется вашими данными, как показано в следующей таблице.
| Строковый тип данных | Строковый литерал | Функция |
|---|---|---|
| WCHAR | L"string" | RtlStringCbCatExW |
| char | Строка | RtlStringCbCatExA |
Если 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по