Win32 API 日本語リファレンス
ホームUI.WindowsAndMessaging › wsprintfA

wsprintfA

関数可変長引数
書式指定に従い文字列を生成する(ANSI)。
DLLUSER32.dll文字セットANSI (-A)呼出規約cdeclSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// USER32.dll  (ANSI / -A)
#include <windows.h>

INT wsprintfA(
    LPSTR param0,
    LPCSTR param1,
    ...
);
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。

パラメーター

名前方向説明
param0LPSTRout書式化結果を受け取る出力ANSIバッファ。
param1LPCSTRin書式指定文字列を表すANSI文字列。以降に可変個の引数が続く。

戻り値の型: INT

公式ドキュメント

指定したバッファーに書式化したデータを書き込みます。(ANSI)

戻り値

型: int

関数が成功すると、戻り値は出力バッファーに格納された文字数(終端の null 文字は含まない)になります。

関数が失敗すると、戻り値は期待される出力の長さより小さくなります。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

書式制御文字列には、lpFmt パラメーターに続く引数の出力形式を決定する書式指定が含まれます。以下で説明する書式指定は、常にパーセント記号 (%) で始まります。パーセント記号の後に書式フィールドとして意味を持たない文字が続く場合、その文字は書式化されません(たとえば %% は単一のパーセント記号文字を生成します)。

書式制御文字列は左から右に読み取られます。最初の書式指定(存在する場合)が現れると、書式制御文字列の後の最初の引数の値が書式指定に従って変換され、出力バッファーにコピーされます。2 番目の書式指定は 2 番目の引数を変換してコピーし、以下同様に続きます。書式指定より引数の数が多い場合、余分な引数は無視されます。すべての書式指定に対して引数が足りない場合、結果は未定義です。

書式指定は次の形式を持ちます。

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

各フィールドは、特定の書式オプションを表す 1 文字または数値です。最後の省略可能な書式フィールドの後に現れる type 文字は、対応する引数を文字、文字列、または数値のいずれとして解釈するかを決定します。最も単純な書式指定は、パーセント記号と type 文字のみで構成されます(たとえば %s)。省略可能なフィールドは、書式化のその他の側面を制御します。以下は、省略可能なフィールドと必須のフィールド、およびそれらの意味です。

フィールド 意味
- 出力を空白またはゼロで右側に埋めてフィールド幅を満たし、出力を左揃えにします。このフィールドを省略した場合、出力は左側に埋められ、右揃えになります。
# 16 進数値に 0x(小文字)または 0X(大文字)を接頭辞として付けます。
0 出力値をゼロで埋めてフィールド幅を満たします。このフィールドを省略した場合、出力値は空白で埋められます。
width 指定した最小文字数を出力バッファーにコピーします。width フィールドは非負の整数です。width の指定によって値が切り捨てられることはありません。出力値の文字数が指定した幅より多い場合、または width フィールドが存在しない場合は、precision 指定に従って値のすべての文字が出力されます。
.precision 数値の場合、指定した最小桁数を出力バッファーにコピーします。引数の桁数が指定した精度より少ない場合、出力値は左側にゼロが埋められます。桁数が指定した精度を超える場合でも値は切り捨てられません。指定した精度が 0 の場合、完全に省略された場合、またはピリオド (.) の後に数値が続かない場合は、精度は 1 に設定されます。

文字列の場合、指定した最大文字数を出力バッファーにコピーします。

type 対応する引数を文字、文字列、または数値として出力します。このフィールドには次のいずれかの値を指定できます。
c
単一文字。この値は wsprintfA では型 CHAR として、wsprintfW では型 WCHAR として解釈されます。wsprintfwsprintfA(Unicode が未定義の場合)または wsprintfW(Unicode が定義されている場合)として定義されるマクロである点に注意してください。
C
単一文字。この値は wsprintfA では型 WCHAR として、wsprintfW では型 CHAR として解釈されます。wsprintfwsprintfA(Unicode が未定義の場合)または wsprintfW(Unicode が定義されている場合)として定義されるマクロである点に注意してください。
d
符号付き 10 進整数。この値は i と等価です。
hc, hC
単一文字。文字の数値が 0 の場合は無視されます。この値は、呼び出し元のアプリケーションが Unicode を定義している場合でも、常に型 CHAR として解釈されます。
hd
符号付き short 整数引数。
hs, hS
文字列。この値は、呼び出し元のアプリケーションが Unicode を定義している場合でも、常に型 LPSTR として解釈されます。
hu
符号なし short 整数。
i
符号付き 10 進整数。この値は d と等価です。
Ix, IX
64 ビットプラットフォームでは小文字または大文字の 64 ビット符号なし 16 進整数、32 ビットプラットフォームでは小文字または大文字の 32 ビット符号なし 16 進整数。
lc, lC
単一文字。文字の数値が 0 の場合は無視されます。この値は、呼び出し元のアプリケーションが Unicode を定義している場合でも、常に型 WCHAR として解釈されます。
ld
long 符号付き整数。この値は li と等価です。
li
long 符号付き整数。この値は ld と等価です。
ls, lS
文字列。この値は、呼び出し元のアプリケーションが Unicode を定義していない場合でも、常に型 LPWSTR として解釈されます。この値は ws と等価です。
lu
long 符号なし整数。
lx, lX
小文字または大文字の long 符号なし 16 進整数。
p
ポインター。アドレスは 16 進数を使用して出力されます。
s
文字列。この値は wsprintfA では型 LPSTR として、wsprintfW では型 LPWSTR として解釈されます。wsprintfwsprintfA(Unicode が未定義の場合)または wsprintfW(Unicode が定義されている場合)として定義されるマクロである点に注意してください。
S
文字列。この値は wsprintfA では型 LPWSTR として、wsprintfW では型 LPSTR として解釈されます。wsprintfwsprintfA(Unicode が未定義の場合)または wsprintfW(Unicode が定義されている場合)として定義されるマクロである点に注意してください。
u
符号なし整数引数。
x, X
小文字または大文字の符号なし 16 進整数。
注意 wsprintf は標準呼び出し (_stdcall) 呼び出し規約ではなく、C 呼び出し規約 (_cdecl) を使用する点に注意することが重要です。その結果、引数をスタックからポップする責任は呼び出し元プロセスにあり、引数は右から左へスタックにプッシュされます。C 言語モジュールでは、C コンパイラーがこの処理を行います。
1024 バイトより大きいバッファーを使用するには、_snwprintf を使用してください。詳細については、C ランタイムライブラリのドキュメントを参照してください。
メモ

winuser.h ヘッダーは wsprintf を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義します。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存ではないコードと混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致につながる可能性があります。詳細については、「Conventions for Function Prototypes」を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// USER32.dll  (ANSI / -A)
#include <windows.h>

INT wsprintfA(
    LPSTR param0,
    LPCSTR param1,
    ...
);
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
[DllImport("USER32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true, CallingConvention = CallingConvention.Cdecl)]
static extern int wsprintfA(
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder param0,   // LPSTR out
    [MarshalAs(UnmanagedType.LPStr)] string param1,   // LPCSTR
    __arglist
);
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
<DllImport("USER32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True, CallingConvention:=CallingConvention.Cdecl)>
Public Shared Function wsprintfA(
    <MarshalAs(UnmanagedType.LPStr)> param0 As System.Text.StringBuilder,   ' LPSTR out
    <MarshalAs(UnmanagedType.LPStr)> param1 As String   ' LPCSTR
) As Integer
End Function
' ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
' param0 : LPSTR out
' param1 : LPCSTR
Declare PtrSafe Function wsprintfA Lib "user32" ( _
    ByVal param0 As String, _
    ByVal param1 As String) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
' ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import ctypes
from ctypes import wintypes

wsprintfA = ctypes.cdll.user32.wsprintfA
wsprintfA.restype = ctypes.c_int
wsprintfA.argtypes = [
    wintypes.LPSTR,  # param0 : LPSTR out
    wintypes.LPCSTR,  # param1 : LPCSTR
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('USER32.dll')
wsprintfA = Fiddle::Function.new(
  lib['wsprintfA'],
  [
    Fiddle::TYPE_VOIDP,  # param0 : LPSTR out
    Fiddle::TYPE_VOIDP,  # param1 : LPCSTR
  ],
  Fiddle::TYPE_INT, Fiddle::Function::CDECL)
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
#[link(name = "user32")]
extern "C" {
    fn wsprintfA(
        param0: *mut u8,  // LPSTR out
        param1: *const u8,  // LPCSTR
        ...
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
$sig = @"
[DllImport("USER32.dll", CharSet = CharSet.Ansi, SetLastError = true, CallingConvention = CallingConvention.Cdecl)]
public static extern int wsprintfA([MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder param0, [MarshalAs(UnmanagedType.LPStr)] string param1);
"@
$api = Add-Type -MemberDefinition $sig -Name 'USER32_wsprintfA' -Namespace Win32 -PassThru
# $api::wsprintfA(param0, param1)
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
#uselib "USER32.dll"
#func global wsprintfA "wsprintfA" sptr, sptr
; wsprintfA varptr(param0), param1   ; 戻り値は stat
; param0 : LPSTR out -> "sptr"
; param1 : LPCSTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
; ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
出力引数:
#uselib "USER32.dll"
#cfunc global wsprintfA "wsprintfA" var, str
; res = wsprintfA(param0, param1)
; param0 : LPSTR out -> "var"
; param1 : LPCSTR -> "str"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
; ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
出力引数:
; INT wsprintfA(LPSTR param0, LPCSTR param1)
#uselib "USER32.dll"
#cfunc global wsprintfA "wsprintfA" var, str
; res = wsprintfA(param0, param1)
; param0 : LPSTR out -> "var"
; param1 : LPCSTR -> "str"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
; ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	user32 = windows.NewLazySystemDLL("USER32.dll")
	procwsprintfA = user32.NewProc("wsprintfA")
)

// param0 (LPSTR out), param1 (LPCSTR)
r1, _, err := procwsprintfA.Call(
	uintptr(param0),
	uintptr(unsafe.Pointer(windows.BytePtrFromString(param1))),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
function wsprintfA(
  param0: PAnsiChar;   // LPSTR out
  param1: PAnsiChar   // LPCSTR
): Integer; cdecl; varargs;
  external 'USER32.dll' name 'wsprintfA';
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
result := DllCall("USER32\wsprintfA"
    , "Ptr", param0   ; LPSTR out
    , "AStr", param1   ; LPCSTR
    , "Cdecl Int")   ; return: INT
; ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
●wsprintfA(param0, param1) = DLL("USER32.dll", "int wsprintfA(char*, char*)")
# 呼び出し: wsprintfA(param0, param1)
# param0 : LPSTR out -> "char*"
# param1 : LPCSTR -> "char*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※cdecl関数。DLL()宣言はstdcall前提。cdeclは EXEC_PTR(`cdecl`,…) を使用。
# ※可変長引数。DLL()は固定引数のみ。追加引数は EXEC_PTR で渡してください。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
const std = @import("std");

extern "user32" fn wsprintfA(
    param0: [*c]u8, // LPSTR out
    param1: [*c]const u8, // LPCSTR
    ...
) callconv(.c) i32;
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
proc wsprintfA(
    param0: ptr char,  # LPSTR out
    param1: cstring  # LPCSTR
): int32 {.importc: "wsprintfA", cdecl, varargs, dynlib: "USER32.dll".}
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
pragma(lib, "user32");
extern(C)
int wsprintfA(
    char* param0,   // LPSTR out
    const(char)* param1,   // LPCSTR
    ...
);
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
ccall((:wsprintfA, "USER32.dll"), Int32,
      (Ptr{UInt8}, Cstring),
      param0, param1)
# param0 : LPSTR out -> Ptr{UInt8}
# param1 : LPCSTR -> Cstring
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
local ffi = require("ffi")
ffi.cdef[[
int32_t wsprintfA(
    char* param0,
    const char* param1,
    ...);
]]
local user32 = ffi.load("user32")
-- user32.wsprintfA(param0, param1)
-- param0 : LPSTR out
-- param1 : LPCSTR
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
const koffi = require('koffi');
const lib = koffi.load('USER32.dll');
const wsprintfA = lib.func('__cdecl', 'wsprintfA', 'int32_t', ['char *', 'str', '...']);
// wsprintfA(param0, param1)
// param0 : LPSTR out -> 'char *'
// param1 : LPCSTR -> 'str'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
const lib = Deno.dlopen("USER32.dll", {
  wsprintfA: { parameters: ["buffer", "buffer"], result: "i32" },
});
// lib.symbols.wsprintfA(param0, param1)
// param0 : LPSTR out -> "buffer"
// param1 : LPCSTR -> "buffer"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
<?php
$ffi = FFI::cdef(<<<C
int32_t wsprintfA(
    char* param0,
    const char* param1,
    ...);
C, "USER32.dll");
// $ffi->wsprintfA(param0, param1);
// param0 : LPSTR out
// param1 : LPCSTR
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface User32 extends Library {
    User32 INSTANCE = Native.load("user32", User32.class, W32APIOptions.ASCII_OPTIONS);
    int wsprintfA(
        byte[] param0,   // LPSTR out
        String param1,   // LPCSTR
        Object... args   // 可変長引数(printf形式)
    );
}
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
@[Link("user32")]
lib LibUSER32
  fun wsprintfA = wsprintfA(
    param0 : UInt8*,   # LPSTR out
    param1 : UInt8*,   # LPCSTR
    ...
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef wsprintfANative = Int32 Function(Pointer<Utf8>, Pointer<Utf8>);
typedef wsprintfADart = int Function(Pointer<Utf8>, Pointer<Utf8>);
final wsprintfA = DynamicLibrary.open('USER32.dll')
    .lookupFunction<wsprintfANative, wsprintfADart>('wsprintfA');
// param0 : LPSTR out -> Pointer<Utf8>
// param1 : LPCSTR -> Pointer<Utf8>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
{$mode objfpc}{$H+}
function wsprintfA(
  param0: PAnsiChar;   // LPSTR out
  param1: PAnsiChar   // LPCSTR
): Integer; cdecl; varargs;
  external 'USER32.dll' name 'wsprintfA';
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import ccall safe "wsprintfA"
  c_wsprintfA :: CString -> CString -> IO Int32
-- param0 : LPSTR out -> CString
-- param1 : LPCSTR -> CString
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
-- ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
open Ctypes
open Foreign

let wsprintfa =
  foreign "wsprintfA"
    (string @-> string @-> returning int32_t)
(* param0 : LPSTR out -> string *)
(* param1 : LPCSTR -> string *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(* ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
(cffi:define-foreign-library user32 (t "USER32.dll"))
(cffi:use-foreign-library user32)

(cffi:defcfun ("wsprintfA" wsprintf-a :convention :cdecl) :int32
  (param0 :pointer)   ; LPSTR out
  (param1 :string)   ; LPCSTR
  &rest)   ; 可変長引数(printf形式)
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
; ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
use Win32::API;
my $wsprintfA = Win32::API::More->new('USER32',
    'int wsprintfA(LPSTR param0, LPCSTR param1)');
# my $ret = $wsprintfA->Call($param0, $param1);
# param0 : LPSTR out -> LPSTR
# param1 : LPCSTR -> LPCSTR
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。

関連項目

文字セット違い
公式の関連項目