RtlStringCbCopyExA 函数 (ntstrsafe.h)

RtlStringCbCopyExWRtlStringCbCopyExA 函数将字节计数的字符串复制到缓冲区中。

语法

NTSTRSAFEDDI RtlStringCbCopyExA(
  [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
);

参数

[out, optional] pszDest

指向接收复制字符串的调用方提供的缓冲区的指针。 pszSrc 处的字符串将复制到 pszDest 处的缓冲区,并终止为 null 字符。 pszDest 指针可以为 NULL,但仅在 dwFlags 中设置STRSAFE_IGNORE_NULLS时。

[in] cbDest

目标缓冲区的大小(以字节为单位)。 缓冲区对于字符串和终止 null 字符必须足够大。

对于 Unicode 字符串,最大字节数为 NTSTRSAFE_MAX_CCH * sizeof(WCHAR)

对于 ANSI 字符串,最大字节数为 NTSTRSAFE_MAX_CCH * sizeof(char)

如果 pszDestNULLcbDest 必须为零。

[in, optional] pszSrc

指向调用方提供的空终止字符串的指针。 pszSrc 指针可以为 NULL,但前提是在 dwFlags 中设置了STRSAFE_IGNORE_NULLS。

[out, optional] ppszDestEnd

如果调用方提供非 NULL 地址指针,则在复制操作完成后,该函数会将该地址与指向目标缓冲区生成的 NULL 字符串终止符的指针一起加载该地址。

[out, optional] pcbRemaining

如果调用方提供非 NULL 地址指针,则该函数将加载包含 pszDest 指向的缓冲区中未使用的字节数的地址,包括用于终止 null 字符的字节。

[in] dwFlags

一个或多个标志(可选)填充字节。 标志的定义如下:

Value 含义
STRSAFE_FILL_BEHIND_NULL 如果设置此标志并且函数成功, 则 dwFlags 的低字节用于填充终止 null 字符之后的目标缓冲区部分。
STRSAFE_IGNORE_NULLS 如果设置了此标志,则 pszDest 或 pszSrc 或两者都可以为 NULL NULLpszSrc 指针被视为空字符串, (TEXT (“”) ) ,可以复制。 NULLpszDest 指针无法接收无空字符串。
STRSAFE_FILL_ON_FAILURE 如果设置了此标志并且函数失败, 则 dwFlags 的低字节用于填充整个目标缓冲区,并且缓冲区为 null 终止。 此操作覆盖任何预先存在的缓冲区内容。
STRSAFE_NULL_ON_FAILURE 如果设置了此标志并且函数失败,则目标缓冲区设置为空字符串, (TEXT (“”) ) 。 此操作覆盖任何预先存在的缓冲区内容。
STRSAFE_NO_TRUNCATION

如果设置了此标志,并且函数返回 STATUS_BUFFER_OVERFLOW

  • 如果还指定 了STRSAFE_FILL_ON_FAILURESTRSAFE_NO_TRUNCATION 相应地填充目标缓冲区。
  • 否则,即使未设置 STRSAFE_NULL_ON_FAILURE ,目标缓冲区的内容也会设置为空字符串。 忽略STRSAFE_FILL_BEHIND_NULL

返回值

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

返回代码 说明
STATUS_SUCCESS 成功 状态表示源数据存在、字符串在没有截断的情况下复制,并且生成的目标缓冲区为 null 终止。
STATUS_BUFFER_OVERFLOW 警告 状态意味着由于目标缓冲区中空间不足而复制操作未完成。 如果设置了 STRSAFE_NO_TRUNCATION ,请参阅 dwFlags 参数以了解详细信息。
STATUS_INVALID_PARAMETER

此错误状态表示函数收到了无效的输入参数。 有关详细信息,请参阅以下段落。

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

  • 指定了无效标志。
  • cbDest 中的值大于最大缓冲区大小。
  • 目标缓冲区已满。
  • 没有STRSAFE_IGNORE_NULLS标志,则存在 NULL 指针。
  • 目标缓冲区指针为 NULL,但缓冲区大小不为零。
  • 目标缓冲区指针为 NULL,或者其长度为零,但存在非零长度源字符串。

注解

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

  • strcpy
  • wcscpy

目标缓冲区的大小(以字节为单位)提供给 RtlStringCbCopyExARtlStringCbCopyExW ,以确保它们不会写入缓冲区末尾。

RtlStringCbCopyEx 通过返回指向目标字符串末尾的指针以及该字符串中未使用的字节数,从而增加了 RtlStringCbCopy 的功能。 可以将标志传递给函数以获取其他控件。

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

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

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

除非设置了STRSAFE_IGNORE_NULLS标志,否则 pszSrcpszDest 都不能为 NULL ,在这种情况下,或两者都可以为 NULL。 如果 pszDestNULLpszSrc 必须为 NULL 或指向空字符串。

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

要求

   
最低受支持的客户端 在 Windows XP 中提供 Service Pack 1 (SP1) 及更高版本的 Windows。
目标平台 台式机
标头 ntstrsafe.h (包括 Ntstrsafe.h)
Library Ntstrsafe.lib
IRQL PASSIVE_LEVEL

另请参阅