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

  • Статья

RtlStringCchCatNExW и функции RtlStringCchCatNExA объединяют две символьные строки при ограничении размера добавленной строки.

Синтаксис

NTSTRSAFEDDI RtlStringCchCatNExA(
  [in, out, optional] NTSTRSAFE_PSTR pszDest,
  [in]                size_t         cchDest,
  [in, optional]      STRSAFE_PCNZCH pszSrc,
                      size_t         cchToAppend,
  [out, optional]     NTSTRSAFE_PSTR *ppszDestEnd,
  [out, optional]     size_t         *pcchRemaining,
  [in]                DWORD          dwFlags
);

Параметры

[in, out, optional] pszDest

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

[in] cchDest

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

[in, optional] pszSrc

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

cchToAppend

Максимальное число символов, добавляемых к строке, содержащейся в буфере, по pszDest.

[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, или его длина составила нулю, но в исходной строке ненулевой длины присутствует.

Замечания

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

  • strncat
  • wcsncat

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

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

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

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

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

См. также