wsprintfA 函数 (winuser.h)

项目
02/01/2024

将格式化的数据写入指定的缓冲区。根据格式字符串中的相应格式规范，转换任何参数并将其复制到输出缓冲区。函数将终止 null 字符追加到其写入的字符，但返回值在其字符计数中不包括终止 null 字符。

注意请勿使用。请考虑改用以下函数之一： StringCbPrintf、 StringCbPrintfEx、 StringCchPrintf 或 StringCchPrintfEx。请参阅安全注意事项。

语法

int WINAPIV wsprintfA(
  [out] LPSTR  unnamedParam1,
  [in]  LPCSTR unnamedParam2,
        ...    
);

参数

[out] unnamedParam1

类型： LPTSTR

要接收格式化输出的缓冲区。缓冲区的最大大小为 1,024 字节。

[in] unnamedParam2

类型： LPCTSTR

格式控制规范。除了普通 ASCII 字符外，此字符串中还显示了每个参数的格式规范。有关格式规范的详细信息，请参阅“备注”部分。

...

一个或多个可选参数。参数的数量和类型取决于 lpFmt 参数中的相应格式控制规范。

返回值

类型： int

如果函数成功，则返回值是输出缓冲区中存储的字符数，不计算终止 null 字符。

如果函数失败，则返回值小于预期输出的长度。要获得更多的错误信息，请调用 GetLastError。

注解

格式控制字符串包含格式规范，这些规范确定 lpFmt 参数后面的参数的输出格式。下面讨论的格式规范始终以百分号 (%) 开头。如果百分号后跟没有意义的字符作为格式字段，则该字符不会 (例如，%% 生成一个百分号字符) 。

格式控制字符串从左到右读取。当第一个格式规范 (如果遇到任何) 时，它会导致转换格式控制字符串后的第一个参数的值，并根据格式规范复制到输出缓冲区。第二个格式规范会导致转换和复制第二个参数，依此而论。如果参数多于格式规范，则忽略额外的参数。如果没有足够的参数用于所有格式规范，则结果为未定义。

格式规范具有以下形式：

%[-][#][0][width][.precision]type

每个字段都是表示特定格式选项的单个字符或数字。最后一个可选格式字段后出现的类型字符决定了关联的参数是解释为字符、字符串还是数字。最简单的格式规范仅包含百分号和类型字符 (例如%s) 。可选字段控制格式设置的其他方面。以下是可选字段和必填字段及其含义。

字段	含义
-	向右填充空白或零以填充字段宽度，使输出向左对齐。如果省略此字段，输出将填充到左侧，使其向右对齐。
#	在十六进制值前面加上 0x (小写) 或 0X (大写) 。
0	用零填充输出值以填充字段宽度。如果省略此字段，则输出值将填充空格。
width	将指定的最小字符数复制到输出缓冲区。宽度字段是一个非否定整数。宽度规范永远不会导致值被截断;如果输出值中的字符数大于指定的宽度，或者如果宽度字段不存在，则根据精度规范打印值的所有字符。
.精度	对于数字，将指定的最小位数复制到输出缓冲区。如果参数中的位数小于指定的精度，则输出值在左侧填充零。当位数超过指定的精度时，不会截断该值。如果指定的精度为 0 或完全省略，或者如果出现句点 (.) 后没有数字，则精度设置为 1。对于字符串，将指定的最大字符数复制到输出缓冲区。
type	将相应的参数输出为字符、字符串或数字。此字段可以是以下任何值。 `c` 单个字符。此值由 wsprintfA 解释为 CHAR 类型，wsprintfW 解释为类型 WCHAR。注意 wsprintf 是一个宏，定义为 wsprintfA (Unicode 未) 或 wsprintfW () 定义的 Unicode。 `C` 单个字符。此值由 wsprintfA 解释为类型 WCHAR，wsprintfW 解释为 CHAR 类型。注意 wsprintf 是一个宏，定义为 wsprintfA (Unicode 未) 或 wsprintfW () 定义的 Unicode。 `d` 带符号十进制整数。此值等效于 `i`。 `hc`, `hC` 单个字符。如果字符的数值为零，则忽略该字符。此值始终解释为 CHAR 类型，即使调用应用程序定义了 Unicode 也是如此。 `hd` 带符号短整数参数。 `hs`, `hS` 字符串。即使调用应用程序定义了 Unicode，此值也始终被解释为类型 LPSTR。 `hu` 无符号短整数。 `i` 带符号十进制整数。此值等效于 `d`。 `Ix`, `IX` 64 位平台上的 64 位无符号十六进制整数（小写或大写），在 32 位平台上，32 位无符号十六进制整数（小写或大写）。 `lc`, `lC` 单个字符。如果字符的数值为零，则忽略该字符。此值始终解释为 WCHAR 类型，即使调用应用程序定义了 Unicode 也是如此。 `ld` 长符号整数。此值等效于 `li`。 `li` 长符号整数。此值等效于 `ld`。 `ls`, `lS` 字符串。此值始终被解释为类型 LPWSTR，即使调用应用程序未定义 Unicode 也是如此。此值等效于 `ws`。 `lu` 长无符号整数。 `lx`, `lX` 长无符号十六进制整数（小写或大写）。 `p` 指针。地址使用十六进制打印。 `s` 字符串。此值由 wsprintfA 解释为类型 LPSTR，由 wsprintfW 解释为类型 LPWSTR。注意 wsprintf 是一个宏，定义为 wsprintfA (Unicode 未) 或 wsprintfW () 定义的 Unicode。 `S` 字符串。此值由 wsprintfA 解释为类型 LPWSTR，由 wsprintfW 解释为类型 LPSTR。注意 wsprintf 是一个宏，定义为 wsprintfA (Unicode 未) 或 wsprintfW () 定义的 Unicode。 `u` 无符号整数参数。 `x`, `X` 小写或大写的无符号十六进制整数。

注意请务必注意， wsprintf 使用 C 调用约定 (_cdecl) ，而不是使用标准调用 (_stdcall) 调用约定。因此，调用进程负责将参数从堆栈中弹出，并将参数从右向左推送到堆栈上。在 C 语言模块中，C 编译器执行此任务。

若要使用大于 1024 字节的缓冲区，请使用 _snwprintf。有关详细信息，请参阅 C 运行时库的文档。

注意

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

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll