RtlStringCchPrintfExA 函数 (ntstrsafe.h)

RtlStringCchPrintfExWRtlStringCchPrintfExA 函数创建字符计数文本字符串,其格式基于提供的格式设置信息。

语法

NTSTRSAFEDDI RtlStringCchPrintfExA(
  [out, optional] NTSTRSAFE_PSTR  pszDest,
  [in]            size_t          cchDest,
  [out, optional] NTSTRSAFE_PSTR  *ppszDestEnd,
  [out, optional] size_t          *pcchRemaining,
  [in]            DWORD           dwFlags,
  [in]            NTSTRSAFE_PCSTR pszFormat,
                  ...             
);

参数

[out, optional] pszDest

指向调用方提供的缓冲区的指针,该缓冲区接收格式化的以 null 结尾的字符串。 函数从 pszFormat 提供的格式字符串和函数的参数列表创建此字符串。 pszDest 指针可以为 NULL,但前提是在 dwFlags 中设置了STRSAFE_IGNORE_NULLS。

[in] cchDest

目标缓冲区的大小(以字符为单位)。 缓冲区必须足够大,才能包含格式化字符串以及终止 null 字符。 允许的最大字符数为NTSTRSAFE_MAX_CCH。 如果 pszDestNULL则 cchDest 必须为零。

[out, optional] ppszDestEnd

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

[out, optional] pcchRemaining

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

[in] dwFlags

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

含义
STRSAFE_FILL_BEHIND_NULL
如果设置且函数成功,则 dwFlags 的低字节用于填充目标缓冲区中紧跟终止 null 字符的部分。
STRSAFE_IGNORE_NULLS
如果设置, pszDest pszSrc 或两者都可以为 NULLNULLpszSrc 指针被视为空字符串 (TEXT (“”) ) ,可以复制。 NULLpszDest 指针无法接收非空字符串。
STRSAFE_FILL_ON_FAILURE
如果设置且函数失败,则 使用 dwFlags 的低字节填充整个目标缓冲区,并且缓冲区以 null 结尾。 此操作将覆盖任何预先存在的缓冲区内容。
STRSAFE_NULL_ON_FAILURE
如果设置且函数失败,则目标缓冲区将设置为 TEXT (“”) ) (空字符串。 此操作将覆盖任何预先存在的缓冲区内容。
STRSAFE_NO_TRUNCATION
如果设置并且函数返回STATUS_BUFFER_OVERFLOW,则不会修改目标缓冲区的内容。

[in] pszFormat

指向包含 printf 样式格式指令的以 null 结尾的文本字符串的指针。 pszFormat 指针可以为 NULL,但前提是在 dwFlags 中设置了STRSAFE_IGNORE_NULLS。

...

函数基于 pszFormat 字符串中包含的格式设置指令解释的参数的可选列表。

返回值

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

返回代码 说明
STATUS_SUCCESS
成功 状态意味着源数据已存在,输出字符串是在未截断的情况下创建的,生成的目标缓冲区以 null 结尾。
STATUS_BUFFER_OVERFLOW
警告 状态表示由于目标缓冲区中的空间不足,操作未完成。 如果在 dwFlags 中设置了STRSAFE_NO_TRUNCATION,则不会修改目标缓冲区。 如果未设置标志,则目标缓冲区包含所创建字符串的截断版本。
STATUS_INVALID_PARAMETER
此错误状态表示函数收到了无效的输入参数。 有关详细信息,请参阅以下段落。

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

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

注解

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

  • sprintf
  • swprintf
  • _snprintf
  • _snwprintf
所有这些函数都接受格式字符串和参数列表,并返回格式化字符串。 RtlStringCchPrintfExWRtlStringCchPrintfExA 接受目标缓冲区的大小(以字符为单位),以确保它们不会写入超过此缓冲区的末尾。

RtlStringCchPrintfExWRtlStringCchPrintfExA 通过返回指向目标字符串末尾的指针以及该字符串中未使用的字符数,为 RtlStringCchPrintf 的功能 添加。 可以将标志传递给 函数,以便进行其他控制。

使用 RtlStringCchPrintfExW 处理 Unicode 字符串,使用 RtlStringCchPrintfExA 处理 ANSI 字符串。 使用的表单取决于你的数据,如下表所示。

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

如果 pszDestpszFormat 指向重叠的字符串,或任何参数字符串重叠,则函数的行为是未定义的。

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

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

要求

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

另请参阅

RtlStringCbPrintfEx

RtlStringCchPrintf

RtlStringCchVPrintfEx