RtlStringCbCopyNA 函数 (ntstrsafe.h)

  • 项目

RtlStringCbCopyNW 和 RtlStringCbCopyNA 函数将字节计数的字符串复制到缓冲区，同时限制复制的字符串的大小。

语法

NTSTRSAFEDDI RtlStringCbCopyNA(
  [out] NTSTRSAFE_PSTR pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_PCNZCH pszSrc,
        size_t         cbToCopy
);

参数

[out] pszDest

指向调用方提供的缓冲区的指针，该缓冲区接收复制的字符串。 pszSrc 中的字符串（最多 cbSrc 字节）将复制到 pszDest 的缓冲区，并使用 null 字符终止。

[in] cbDest

目标缓冲区的大小（以字节为单位）。 缓冲区必须足够大，才能同时包含字符串和终止 null 字符。

对于 Unicode 字符串，最大字节数为 NTSTRSAFE_MAX_CCH * size of (WCHAR) 。

对于 ANSI 字符串，最大字节数为 NTSTRSAFE_MAX_CCH * size of (char) 。

[in] pszSrc

指向调用方提供的以 null 结尾的字符串的指针。

cbToCopy

要从 pszSrc 复制到 pszDest 的最大字节数。

返回值

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

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

函数在以下情况下返回STATUS_INVALID_PARAMETER值：

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

注解

应使用 RtlStringCbCopyNW 和 RtlStringCbCopyNA 而不是 strncpy。 但是，这些函数在行为上有所不同。 如果 cbSrc 大于 pszSrc 中的字节数，则在复制 cbSrc 字节之前，RtlStringCbCopyN 函数（与 strncpy 不同）不会用 null 字符填充 pszDest。

RtlStringCbCopyN 从源字符串复制给定数量的字节。 目标缓冲区的大小（以字节为单位）提供给函数，以确保 RtlStringCbCopyN 不会写入此缓冲区的末尾。

使用 RtlStringCbCopyNW 处理 Unicode 字符串，使用 RtlStringCbCopyNA 处理 ANSI 字符串。 使用的表单取决于你的数据，如下表所示。

字符串数据类型 字符串文本 函数
WCHAR L“string” RtlStringCbCopyNW
char “字符串” RtlStringCbCopyNA
 

如果 pszSrc 和 pszDest 指向重叠字符串，则函数的行为未定义。

pszSrc 和 pszDest 都不能为 NULL。 如果需要处理 NULL 字符串指针值，请参阅 RtlStringCbCopyNEx。

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

要求

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

另请参阅

RtlStringCbCopy

RtlStringCbCopyNEx

RtlStringCchCopyN