Поделиться через

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

  • Статья

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

Синтаксис

NTSTRSAFEDDI RtlStringCchCatExA(
  [in, out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]                size_t          cchDest,
  [in]                NTSTRSAFE_PCSTR pszSrc,
  [out, optional]     NTSTRSAFE_PSTR  *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 для заполнения всего целевого буфера, а буфер завершается значением NULL. Эта операция перезаписывает все предварительно существующие содержимое буфера.
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

См. также