Функция RtlStringCchCatExW (ntstrsafe.h)

  • Статья

RtlStringCchCatExW и RtlStringCchCatExA функции объединяют две символьные строки.

Синтаксис

NTSTRSAFEDDI RtlStringCchCatExW(
  [in, out, optional] NTSTRSAFE_PWSTR  pszDest,
  [in]                size_t           cchDest,
  [in]                NTSTRSAFE_PCWSTR pszSrc,
  [out, optional]     NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional]     size_t           *pcchRemaining,
  [in]                DWORD            dwFlags
);

Параметры

[in, out, optional] pszDest

Указатель на буфер, содержащий строку, завершающуюся значением NULL, к которой pszSrc будет объединена. В выходных данных это целевой буфер, содержащий всю результирующую строку. Строка в pszSrc добавляется в конец строки в pszDest и завершается значением NULL. Указатель pszDest можно null, но только если STRSAFE_IGNORE_NULLS задан в dwFlags.

[in] cchDest

Размер целевого буфера в символах. Максимально допустимое количество символов — NTSTRSAFE_MAX_CCH. Если pszDestNULL, cchDest должно быть равно нулю.

[in] pszSrc

Указатель на строку, завершаемую значением NULL. Эта строка будет объединена в конец строки, содержащейся в буфере в pszDest. Указатель pszSrc может быть null, но только если STRSAFE_IGNORE_NULLS заданы в dwFlags.

[out, optional] ppszDestEnd

Если вызывающий объект предоставляет указатель адреса, отличный отNULL, адрес, то после завершения операции объединения функция загружает этот адрес с указателем на результирующий строковый терминатор конечного буфера.

[out, optional] pcchRemaining

Если вызывающий объект предоставляет указатель адресов, отличный отNULL, функция загружает адрес с числом неиспользуемых символов, которые находятся в буфере, на которые указывает pszDest, включая завершающий символ NULL.

[in] dwFlags

Один или несколько флагов и, при необходимости, байт заливки. Флаги определяются следующим образом:

Ценность Значение
STRSAFE_FILL_BEHIND_NULL Если этот флаг задан и функция успешно выполнена, то для заполнения части конечного буфера используется низкий байт dwFlags.
STRSAFE_IGNORE_NULLS Если этот флаг задан, pszDest или pszSrcили оба параметра могут быть NULL. NULLуказатели pszSrc обрабатываются как пустые строки (TEXT("")), которые можно скопировать. nullpszDest указатели не могут получать строки nonempty.
STRSAFE_FILL_ON_FAILURE Если этот флаг задан и функция завершается ошибкой, то для заполнения всего целевого буфера используется низкий байт dwFlags. Эта операция перезаписывает все предварительно существующие содержимое буфера.
STRSAFE_NULL_ON_FAILURE Если этот флаг задан и функция завершается ошибкой, буфер назначения имеет пустую строку (TEXT("")). Эта операция перезаписывает все предварительно существующие содержимое буфера.
STRSAFE_NO_TRUNCATION

Если этот флаг задан, функция возвращает STATUS_BUFFER_OVERFLOW:

  • Если STRSAFE_FILL_ON_FAILURE также указан, STRSAFE_NO_TRUNCATION заполняет буфер назначения соответствующим образом.
  • В противном случае буфер назначения будет не изменен.

Возвращаемое значение

Функция возвращает одно из значений NTSTATUS, перечисленных в следующей таблице. Сведения об тестировании значений NTSTATUS см. в использование значений NTSTATUS.

Возвращаемый код Описание
STATUS_SUCCESS Это успешном состоянии означает, что исходные данные были представлены, выходная строка была создана без усечения, а результирующий целевой буфер завершается значением NULL.
STATUS_BUFFER_OVERFLOW Это предупреждение о состоянии означает, что операция не завершена из-за нехватки места в целевом буфере. Если задано STRSAFE_NO_TRUNCATION, дополнительные сведения см. в параметре dwFlags dwFlags.
STATUS_INVALID_PARAMETER

Это ошибка состоянии означает, что функция получила недопустимый входной параметр. Дополнительные сведения см. в следующем абзаце.

Функция возвращает значение STATUS_INVALID_PARAMETER, если:

  • Указан недопустимый флаг.
  • Значение в cchDest больше максимального размера буфера.
  • Буфер назначения уже заполнен.
  • Указатель NULL присутствует без флага STRSAFE_IGNORE_NULLS.
  • Указатель целевого буфера был NULL, но размер буфера не был нулем.
  • Указатель на целевой буфер был null, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

RtlStringCchCatExW и RtlStringCchCatExA следует использовать вместо следующих функций:

  • strcat
  • wcscat

Размер буфера назначения предоставляется для обеспечения того, чтобы RtlStringCchCatExW и RtlStringCchCatExA не записывать в конец буфера.

RtlStringCchCatExW и RtlStringCchCatExA добавить в функциональные возможности RtlStringCchCat путем возврата указателя на конец конечной строки, а также количество символов, оставшихся неиспользуемым в буфере назначения. Флаги можно передать функции для дополнительного элемента управления.

Используйте RtlStringCchCatExW для обработки строк Юникода и RtlStringCchCatExA для обработки строк ANSI. Используемая форма зависит от данных.

Тип строковых данных Строковый литерал Функция
WCHAR L"string" RtlStringCchCatExW
char "string" RtlStringCchCatExA

Если pszSrc и pszDest указывать на перекрывающиеся строки, поведение функции не определено.

Ни pszSrc, ни pszDest не могут быть NULL, если флаг STRSAFE_IGNORE_NULLS не задан, в этом случае или оба могут быть NULL. Если pszDestNULL, pszSrc должны быть NULL или указывать на пустую строку.

Дополнительные сведения о функциях безопасной строки см. в разделе Использование безопасных строковых функций.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Доступно в Windows XP с пакетом обновления 1 (SP1) и более поздними версиями Windows.
целевая платформа Настольный
заголовка ntstrsafe.h (include Ntstrsafe.h)
библиотеки Ntstrsafe.lib
IRQL Любой, если управляемые строки всегда находятся в памяти, в противном случае PASSIVE_LEVEL

См. также