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

RtlStringCbCatExW и RtlStringCbCatExA функции объединяют две байтовые строки.

Синтаксис

NTSTRSAFEDDI RtlStringCbCatExA(
  [in, out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]                size_t          cbDest,
  [in, optional]      NTSTRSAFE_PCSTR pszSrc,
  [out, optional]     NTSTRSAFE_PSTR  *ppszDestEnd,
  [out, optional]     size_t          *pcbRemaining,
  [in]                DWORD           dwFlags
);

Параметры

[in, out, optional] pszDest

Указатель на буфер, содержащий строку, завершающуюся значением NULL, к которой 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

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

[out, optional] ppszDestEnd

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

[out, optional] pcbRemaining

Если вызывающий объект предоставляет указатель адресов, отличный от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, когда: Указан недопустимый флаг. Значение в cbDest больше максимального размера буфера. Буфер назначения уже заполнен. Указатель NULL присутствует без флага STRSAFE_IGNORE_NULLS. Указатель целевого буфера был NULL, но размер буфера не был нулем. Указатель на целевой буфер был null, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

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

• strcat
• wcscat

Так как RtlStringCbCatExW и RtlStringCbCatExAполучают размер целевого буфера в качестве входных данных, они не записываются в конец буфера.

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

Используйте RtlStringCbCatExW для обработки строк Юникода и RtlStringCbCatExA для обработки строк ANSI. Используемая форма определяется данными, как показано в следующей таблице.

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

Если 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

См. также

• RtlStringCbCat
• RtlStringCbCatNEx
• RtlStringCchCatEx