RtlStringCchCatNA 函数 (ntstrsafe.h)

RtlStringCchCatNWRtlStringCchCatNA 函数连接两个字符计数字符串,同时限制追加字符串的大小。

语法

NTSTRSAFEDDI RtlStringCchCatNA(
  [in, out] NTSTRSAFE_PSTR pszDest,
  [in]      size_t         cchDest,
  [in]      STRSAFE_PCNZCH pszSrc,
            size_t         cchToAppend
);

参数

[in, out] pszDest

指向缓冲区的指针,该缓冲区在输入时包含以 null 结尾的字符串, pszSrc 将连接到该字符串。 在输出中,这是包含整个结果字符串的目标缓冲区。 pszSrc 处的字符串(最多 cchMaxAppend 字符)将添加到 pszDest 处的字符串末尾,并用 null 字符终止。

[in] cchDest

目标缓冲区的大小(以字符为单位)。 允许的最大字符数为NTSTRSAFE_MAX_CCH。

[in] pszSrc

指向以 null 结尾的字符串的指针。 此字符串将连接到 pszDest 处缓冲区中包含的字符串的末尾。

cchToAppend

要追加到 pszDest 处缓冲区中包含的字符串的最大字符数。

返回值

该函数返回下表中列出的 NTSTATUS 值之一。 有关如何测试 NTSTATUS 值的信息,请参阅 使用 NTSTATUS 值

返回代码 说明
STATUS_SUCCESS
成功 状态表示存在源数据,字符串已连接而不截断,结果目标缓冲区以 null 结尾。
STATUS_BUFFER_OVERFLOW
警告 状态表示由于缓冲区空间不足而未完成串联操作。 目标缓冲区包含截断的、以 null 结尾的预期结果版本。
STATUS_INVALID_PARAMETER
此错误状态表示函数收到了无效的输入参数。 有关详细信息,请参阅以下段落。

在以下情况下,函数返回STATUS_INVALID_PARAMETER值:

  • cchDest 中的值大于最大缓冲区大小。
  • 目标缓冲区已满。
  • 存在 NULL 指针。
  • 目标缓冲区的长度为零,但存在非零长度源字符串。

注解

应使用 RtlStringCchCatNWRtlStringCchCatNA,而不是以下函数:

  • strncat
  • wcsncat
目标缓冲区的大小(以字符为单位)提供给函数,以确保 RtlStringCchCatNWRtlStringCchCatNA 不会写入缓冲区末尾。

使用 RtlStringCchCatNW 处理 Unicode 字符串,使用 RtlStringCchCatNA 处理 ANSI 字符串。 使用的窗体取决于你的数据,如下表所示。

字符串数据类型 字符串文本 函数
WCHAR L“string” RtlStringCchCatNW
字符 “字符串” RtlStringCchCatNA
 

如果 pszSrcpszDest 指向重叠字符串,则函数的行为未定义。

pszSrcpszDest 都不能为 NULL。 如果需要处理 NULL 字符串指针值,请使用 RtlStringCchCatNEx

有关安全字符串函数的详细信息,请参阅 使用安全字符串函数

要求

要求
最低受支持的客户端 在 Windows 的 Service Pack 1 (SP1) 及更高版本的 Windows 中可用。
目标平台 桌面
标头 ntstrsafe.h (包括 Ntstrsafe.h)
Library Ntstrsafe.lib
IRQL 如果正在操作的字符串始终驻留在内存中,则为 Any,否则PASSIVE_LEVEL

另请参阅

RtlStringCbCatN

RtlStringCchCat

RtlStringCchCatNEx