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

wsprintfW

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

シグネチャ

// USER32.dll  (Unicode / -W)
#include <windows.h>

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

パラメーター

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

戻り値の型: INT

公式ドキュメント

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

戻り値

型: int

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

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

解説(Remarks)

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

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

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

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

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

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

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

type 対応する引数を文字、文字列、または数値として出力します。このフィールドには次のいずれかの値を指定できます。
c
単一の文字。この値は wsprintfA では型 CHARwsprintfW では型 WCHAR として解釈されます。wsprintf は、wsprintfA(Unicode 未定義時)または wsprintfW(Unicode 定義時)として定義されるマクロである点に注意してください。
C
単一の文字。この値は wsprintfA では型 WCHARwsprintfW では型 CHAR として解釈されます。wsprintf は、wsprintfA(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 では型 LPSTRwsprintfW では型 LPWSTR として解釈されます。wsprintf は、wsprintfA(Unicode 未定義時)または wsprintfW(Unicode 定義時)として定義されるマクロである点に注意してください。
S
文字列。この値は wsprintfA では型 LPWSTRwsprintfW では型 LPSTR として解釈されます。wsprintf は、wsprintfA(Unicode 未定義時)または wsprintfW(Unicode 定義時)として定義されるマクロである点に注意してください。
u
符号なし整数の引数。
x, X
小文字または大文字の符号なし 16 進整数。
注意 wsprintf は標準呼び出し (_stdcall) ではなく C の呼び出し規約 (_cdecl) を使用する点に注意することが重要です。その結果、引数をスタックからポップするのは呼び出し元プロセスの責任であり、引数は右から左へスタックにプッシュされます。C 言語のモジュールでは、C コンパイラーがこの処理を行います。
1024 バイトより大きいバッファを使用するには、_snwprintf を使用してください。詳細については、C ランタイムライブラリのドキュメントを参照してください。
メモ

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

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

各言語での呼び出し定義

// USER32.dll  (Unicode / -W)
#include <windows.h>

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

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

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

var (
	user32 = windows.NewLazySystemDLL("USER32.dll")
	procwsprintfW = user32.NewProc("wsprintfW")
)

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

extern "user32" fn wsprintfW(
    param0: [*c]u16, // LPWSTR out
    param1: [*c]const u16, // LPCWSTR
    ...
) callconv(.c) i32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
proc wsprintfW(
    param0: ptr uint16,  # LPWSTR out
    param1: WideCString  # LPCWSTR
): int32 {.importc: "wsprintfW", cdecl, varargs, dynlib: "USER32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
pragma(lib, "user32");
extern(C)
int wsprintfW(
    wchar* param0,   // LPWSTR out
    const(wchar)* param1,   // LPCWSTR
    ...
);
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
ccall((:wsprintfW, "USER32.dll"), Int32,
      (Ptr{UInt16}, Cwstring),
      param0, param1)
# param0 : LPWSTR out -> Ptr{UInt16}
# param1 : LPCWSTR -> Cwstring
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
local ffi = require("ffi")
ffi.cdef[[
int32_t wsprintfW(
    uint16_t* param0,
    const uint16_t* param1,
    ...);
]]
local user32 = ffi.load("user32")
-- user32.wsprintfW(param0, param1)
-- param0 : LPWSTR out
-- param1 : LPCWSTR
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
-- ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
const koffi = require('koffi');
const lib = koffi.load('USER32.dll');
const wsprintfW = lib.func('__cdecl', 'wsprintfW', 'int32_t', ['uint16_t *', 'str16', '...']);
// wsprintfW(param0, param1)
// param0 : LPWSTR out -> 'uint16_t *'
// param1 : LPCWSTR -> 'str16'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
const lib = Deno.dlopen("USER32.dll", {
  wsprintfW: { parameters: ["buffer", "buffer"], result: "i32" },
});
// lib.symbols.wsprintfW(param0, param1)
// param0 : LPWSTR out -> "buffer"
// param1 : LPCWSTR -> "buffer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
<?php
$ffi = FFI::cdef(<<<C
int32_t wsprintfW(
    uint16_t* param0,
    const uint16_t* param1,
    ...);
C, "USER32.dll");
// $ffi->wsprintfW(param0, param1);
// param0 : LPWSTR out
// param1 : LPCWSTR
// 構造体/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.UNICODE_OPTIONS);
    int wsprintfW(
        char[] param0,   // LPWSTR out
        WString param1,   // LPCWSTR
        Object... args   // 可変長引数(printf形式)
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
// ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
@[Link("user32")]
lib LibUSER32
  fun wsprintfW = wsprintfW(
    param0 : UInt16*,   # LPWSTR out
    param1 : UInt16*,   # LPCWSTR
    ...
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# ※可変長引数(printf形式・cdecl)。上記の固定引数の後に、書式に応じた引数を追加で渡します。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

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

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

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

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

関連項目

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