stringCbPrintfA 函数 (strsafe.h)

将格式化的数据写入指定的字符串。 向函数提供目标缓冲区的大小，以确保它不会写入此缓冲区的末尾。

StringCbPrintf 是以下函数的替代项：

• sprintf、swprintf、_stprintf
• wsprintf
• wnsprintf
• _snprintf、_snwprintf、_sntprintf

语法

STRSAFEAPI StringCbPrintfA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cbDest,
  [in]  STRSAFE_LPCSTR pszFormat,
        ...            
);

参数

[out] pszDest

类型： LPSTR

目标缓冲区，接收从 pszFormat 及其参数创建的格式化的以 null 结尾的字符串。

[in] cbDest

类型： size_t

目标缓冲区的大小（以字节为单位）。 此值必须足够大，以便容纳最终格式化字符串以及终止 null 字符。 允许的最大字节数为 STRSAFE_MAX_CCH * sizeof(TCHAR)。

[in] pszFormat

类型： LPCSTR

格式字符串。 此字符串必须以 null 结尾。 有关详细信息，请参阅 格式规范语法。

...

要插入到 pszFormat 字符串中的参数。

返回值

类型： HRESULT

此函数可以返回以下值之一。 强烈建议使用 SUCCEEDED 和 FAILED 宏来测试此函数的返回值。

返回代码	说明
S_OK	有足够的空间将结果复制到 pszDest 而不截断，并且缓冲区以 null 结尾。
STRSAFE_E_INVALID_PARAMETER	cbDest 中的值是 0 或大于 STRSAFE_MAX_CCH * sizeof(TCHAR)。
STRSAFE_E_INSUFFICIENT_BUFFER	由于缓冲区空间不足，复制操作失败。 目标缓冲区包含截断的、以 null 结尾的预期结果版本。 在可以接受截断的情况下，这可能不一定被视为故障条件。

 

请注意，此函数返回 HRESULT 值，与它替换的函数不同。

注解

与它替换的函数相比， StringCbPrintf 为代码中的正确缓冲区处理提供了额外的处理。 糟糕的缓冲区处理与涉及缓冲区溢出的许多安全问题有关。 StringCbPrintf 始终为 null 终止非零长度的目标缓冲区。

如果 pszDest、 pszFormat 或任何参数字符串指向的字符串重叠，则行为未定义。

pszFormat 和 pszDest 都不应为 NULL。 如果需要处理 null 字符串指针值，请参阅 StringCbPrintfEx 。

StringCbPrintf 可以采用其泛型形式或更具体的形式使用。 字符串的数据类型决定了应使用的此函数的形式。

String 数据类型	字符串	函数
char	“字符串”	StringCbPrintfA
TCHAR	TEXT (“string”)	StringCbPrintf
WCHAR	L“string”	StringCbPrintfW

 

示例

以下示例使用四个参数演示 StringCbPrintf 的基本用法。

int const arraysize = 30;
TCHAR pszDest[arraysize]; 
size_t cbDest = arraysize * sizeof(TCHAR);

LPCTSTR pszFormat = TEXT("%s %d + %d = %d.");
TCHAR* pszTxt = TEXT("The answer is");

HRESULT hr = StringCbPrintf(pszDest, cbDest, pszFormat, pszTxt, 1, 2, 3);

// The resultant string at pszDest is "The answer is 1 + 2 = 3."

注意

strsafe.h 标头将 StringCbPrintf 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

最低受支持的客户端	Windows XP SP2 [桌面应用 |UWP 应用]
最低受支持的服务器	Windows Server 2003 SP1 [桌面应用 |UWP 应用]
目标平台	Windows
标头	strsafe.h

另请参阅

引用

StringCbPrintfEx

StringCbVPrintf

StringCchPrintf