ホーム › Devices.DeviceAndDriverInstallation › SetupCopyErrorA

SetupCopyErrorA

関数

ファイルコピーエラーを通知するダイアログを表示する(ANSI)。

DLLSETUPAPI.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

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

DWORD SetupCopyErrorA(
    HWND hwndParent,
    LPCSTR DialogTitle,   // optional
    LPCSTR DiskName,   // optional
    LPCSTR PathToSource,
    LPCSTR SourceFile,
    LPCSTR TargetPathFile,   // optional
    DWORD Win32ErrorCode,
    DWORD Style,
    LPSTR PathBuffer,   // optional
    DWORD PathBufferSize,
    DWORD* PathRequiredSize   // optional
);

パラメーター

名前	型	方向	説明
hwndParent	HWND	in	このダイアログボックスの親ウィンドウのハンドル。
DialogTitle	LPCSTR	inoptional	ダイアログボックスのタイトルを指定する null 終端文字列への省略可能なポインター。このパラメーターには NULL を指定できます。NULL を指定した場合は、既定のタイトルである "Copy Error" (システムの言語にローカライズされたもの) が使用されます。
DiskName	LPCSTR	inoptional	挿入するディスクの名前を指定する null 終端文字列への省略可能なポインター。このパラメーターには NULL を指定できます。NULL を指定した場合は、既定の名前である "(Unknown)" (システムの言語にローカライズされたもの) が使用されます。
PathToSource	LPCSTR	in	操作が失敗したソースファイルのパス部分 (たとえば F:\x86) へのポインター。 null 終端文字列を使用してください。
SourceFile	LPCSTR	in	操作が失敗したファイルのファイル名部分を指定する null 終端文字列へのポインター。 null 終端文字列を使用してください。このファイル名は、ユーザーが Details (詳細) ボタンまたは Browse (参照) ボタンをクリックしたときに表示されます。SetupCopyError 関数は、圧縮形式の名前を使用してファイルを検索します。そのため、cmd.exe を渡すことができ、ソースメディア上でそのファイルが実際には cmd.ex_ として存在していても問題ありません。
TargetPathFile	LPCSTR	inoptional	名前変更操作およびコピー操作の対象ファイルのフルパスを指定する null 終端文字列への省略可能なポインター。 null 終端文字列を使用してください。このパラメーターには NULL を指定できます。TargetPathFile を指定しない場合は、"(Unknown)" (システムの言語にローカライズされたもの) が使用されます。
Win32ErrorCode	DWORD	in	エラーが発生した場合、このメンバーはシステムエラーコードになります。エラーが発生しなかった場合は NO_ERROR です。
Style	DWORD	in	ダイアログボックスの表示形式と動作を制御するフラグ。このパラメーターには、次のいずれかのフラグを指定できます。 IDF_NOBROWSE 参照オプションを表示しません。 IDF_NOSKIP ファイルのスキップオプションを表示しません。 IDF_NODETAILS 詳細オプションを表示しません。このフラグを設定した場合、TargetPathFile パラメーターと Win32ErrorCode パラメーターは省略できます。 IDF_NOCOMPRESSED ソースファイルの圧縮版を確認しません。 IDF_OEMDISK 操作のソースが、ハードウェア製造元から提供されたディスクであることを示します。 IDF_NOBEEP ダイアログボックスが最初に表示されるときに、ユーザーの注意を引くためのビープ音を鳴らさないようにします。 IDF_NOFOREGROUND ダイアログボックスがフォアグラウンドウィンドウにならないようにします。 IDF_WARNIFSKIP ファイルをスキップするとインストールに影響する可能性があることをユーザーに警告します。
PathBuffer	LPSTR	outoptional	ダイアログボックスでユーザーが指定した場所のパス (ファイル名は含まない) を、この関数が返す変数への省略可能なポインター。null 終端文字列を使用してください。 null 終端文字列は、コピー先バッファーのサイズを超えないようにしてください。バッファー不足のエラーを避けるため、PathBuffer は少なくとも MAX_PATH のサイズにしてください。詳細については、このトピックの「解説」セクションを参照してください。
PathBufferSize	DWORD	in	PathBuffer が指すバッファーのサイズ (文字数)。バッファーサイズは、null 終端文字を含めて少なくとも MAX_PATH 文字にしてください。
PathRequiredSize	DWORD*	outoptional	必要なバッファーサイズ (null 終端文字を含む文字数) を、この関数が返す変数への省略可能なポインター。

戻り値の型: DWORD

公式ドキュメント

SetupCopyError 関数は、ファイルのコピーエラーをユーザーに通知するためのダイアログボックスを生成します。(ANSI)

戻り値

この関数は次のいずれかの値を返します。

拡張エラー情報を取得するには、 GetLastError を呼び出します。

解説(Remarks)

PathBuffer に NULL、PathBufferSize に 0 (ゼロ) を指定してこの関数を呼び出した場合、指定されたデータを格納するために必要なバッファーサイズが、PathRequiredSize が指す変数に格納されます。

関数が成功した場合、戻り値は NO_ERROR です。それ以外の場合、戻り値は指定された値のいずれかになります。

バッファー不足のエラーを避けるため、ReturnBuffer は少なくとも MAX_PATH のサイズにしてください。

メモ

setupapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして SetupCopyError を定義しています。エンコーディング中立のエイリアスと、エンコーディング中立でないコードを混在させて使用すると、不一致が生じてコンパイルエラーや実行時エラーの原因となる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

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

DWORD SetupCopyErrorA(
    HWND hwndParent,
    LPCSTR DialogTitle,   // optional
    LPCSTR DiskName,   // optional
    LPCSTR PathToSource,
    LPCSTR SourceFile,
    LPCSTR TargetPathFile,   // optional
    DWORD Win32ErrorCode,
    DWORD Style,
    LPSTR PathBuffer,   // optional
    DWORD PathBufferSize,
    DWORD* PathRequiredSize   // optional
);

[DllImport("SETUPAPI.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern uint SetupCopyErrorA(
    IntPtr hwndParent,   // HWND
    [MarshalAs(UnmanagedType.LPStr)] string DialogTitle,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string DiskName,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string PathToSource,   // LPCSTR
    [MarshalAs(UnmanagedType.LPStr)] string SourceFile,   // LPCSTR
    [MarshalAs(UnmanagedType.LPStr)] string TargetPathFile,   // LPCSTR optional
    uint Win32ErrorCode,   // DWORD
    uint Style,   // DWORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder PathBuffer,   // LPSTR optional, out
    uint PathBufferSize,   // DWORD
    IntPtr PathRequiredSize   // DWORD* optional, out
);

<DllImport("SETUPAPI.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetupCopyErrorA(
    hwndParent As IntPtr,   ' HWND
    <MarshalAs(UnmanagedType.LPStr)> DialogTitle As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> DiskName As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> PathToSource As String,   ' LPCSTR
    <MarshalAs(UnmanagedType.LPStr)> SourceFile As String,   ' LPCSTR
    <MarshalAs(UnmanagedType.LPStr)> TargetPathFile As String,   ' LPCSTR optional
    Win32ErrorCode As UInteger,   ' DWORD
    Style As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPStr)> PathBuffer As System.Text.StringBuilder,   ' LPSTR optional, out
    PathBufferSize As UInteger,   ' DWORD
    PathRequiredSize As IntPtr   ' DWORD* optional, out
) As UInteger
End Function

' hwndParent : HWND
' DialogTitle : LPCSTR optional
' DiskName : LPCSTR optional
' PathToSource : LPCSTR
' SourceFile : LPCSTR
' TargetPathFile : LPCSTR optional
' Win32ErrorCode : DWORD
' Style : DWORD
' PathBuffer : LPSTR optional, out
' PathBufferSize : DWORD
' PathRequiredSize : DWORD* optional, out
Declare PtrSafe Function SetupCopyErrorA Lib "setupapi" ( _
    ByVal hwndParent As LongPtr, _
    ByVal DialogTitle As String, _
    ByVal DiskName As String, _
    ByVal PathToSource As String, _
    ByVal SourceFile As String, _
    ByVal TargetPathFile As String, _
    ByVal Win32ErrorCode As Long, _
    ByVal Style As Long, _
    ByVal PathBuffer As String, _
    ByVal PathBufferSize As Long, _
    ByVal PathRequiredSize As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SetupCopyErrorA = ctypes.windll.setupapi.SetupCopyErrorA
SetupCopyErrorA.restype = wintypes.DWORD
SetupCopyErrorA.argtypes = [
    wintypes.HANDLE,  # hwndParent : HWND
    wintypes.LPCSTR,  # DialogTitle : LPCSTR optional
    wintypes.LPCSTR,  # DiskName : LPCSTR optional
    wintypes.LPCSTR,  # PathToSource : LPCSTR
    wintypes.LPCSTR,  # SourceFile : LPCSTR
    wintypes.LPCSTR,  # TargetPathFile : LPCSTR optional
    wintypes.DWORD,  # Win32ErrorCode : DWORD
    wintypes.DWORD,  # Style : DWORD
    wintypes.LPSTR,  # PathBuffer : LPSTR optional, out
    wintypes.DWORD,  # PathBufferSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # PathRequiredSize : DWORD* optional, out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SETUPAPI.dll')
SetupCopyErrorA = Fiddle::Function.new(
  lib['SetupCopyErrorA'],
  [
    Fiddle::TYPE_VOIDP,  # hwndParent : HWND
    Fiddle::TYPE_VOIDP,  # DialogTitle : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # DiskName : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # PathToSource : LPCSTR
    Fiddle::TYPE_VOIDP,  # SourceFile : LPCSTR
    Fiddle::TYPE_VOIDP,  # TargetPathFile : LPCSTR optional
    -Fiddle::TYPE_INT,  # Win32ErrorCode : DWORD
    -Fiddle::TYPE_INT,  # Style : DWORD
    Fiddle::TYPE_VOIDP,  # PathBuffer : LPSTR optional, out
    -Fiddle::TYPE_INT,  # PathBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # PathRequiredSize : DWORD* optional, out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "setupapi")]
extern "system" {
    fn SetupCopyErrorA(
        hwndParent: *mut core::ffi::c_void,  // HWND
        DialogTitle: *const u8,  // LPCSTR optional
        DiskName: *const u8,  // LPCSTR optional
        PathToSource: *const u8,  // LPCSTR
        SourceFile: *const u8,  // LPCSTR
        TargetPathFile: *const u8,  // LPCSTR optional
        Win32ErrorCode: u32,  // DWORD
        Style: u32,  // DWORD
        PathBuffer: *mut u8,  // LPSTR optional, out
        PathBufferSize: u32,  // DWORD
        PathRequiredSize: *mut u32  // DWORD* optional, out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SETUPAPI.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern uint SetupCopyErrorA(IntPtr hwndParent, [MarshalAs(UnmanagedType.LPStr)] string DialogTitle, [MarshalAs(UnmanagedType.LPStr)] string DiskName, [MarshalAs(UnmanagedType.LPStr)] string PathToSource, [MarshalAs(UnmanagedType.LPStr)] string SourceFile, [MarshalAs(UnmanagedType.LPStr)] string TargetPathFile, uint Win32ErrorCode, uint Style, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder PathBuffer, uint PathBufferSize, IntPtr PathRequiredSize);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SETUPAPI_SetupCopyErrorA' -Namespace Win32 -PassThru
# $api::SetupCopyErrorA(hwndParent, DialogTitle, DiskName, PathToSource, SourceFile, TargetPathFile, Win32ErrorCode, Style, PathBuffer, PathBufferSize, PathRequiredSize)

#uselib "SETUPAPI.dll"
#func global SetupCopyErrorA "SetupCopyErrorA" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; SetupCopyErrorA hwndParent, DialogTitle, DiskName, PathToSource, SourceFile, TargetPathFile, Win32ErrorCode, Style, varptr(PathBuffer), PathBufferSize, varptr(PathRequiredSize)   ; 戻り値は stat
; hwndParent : HWND -> "sptr"
; DialogTitle : LPCSTR optional -> "sptr"
; DiskName : LPCSTR optional -> "sptr"
; PathToSource : LPCSTR -> "sptr"
; SourceFile : LPCSTR -> "sptr"
; TargetPathFile : LPCSTR optional -> "sptr"
; Win32ErrorCode : DWORD -> "sptr"
; Style : DWORD -> "sptr"
; PathBuffer : LPSTR optional, out -> "sptr"
; PathBufferSize : DWORD -> "sptr"
; PathRequiredSize : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SETUPAPI.dll"
#cfunc global SetupCopyErrorA "SetupCopyErrorA" sptr, str, str, str, str, str, int, int, var, int, var
; res = SetupCopyErrorA(hwndParent, DialogTitle, DiskName, PathToSource, SourceFile, TargetPathFile, Win32ErrorCode, Style, PathBuffer, PathBufferSize, PathRequiredSize)
; hwndParent : HWND -> "sptr"
; DialogTitle : LPCSTR optional -> "str"
; DiskName : LPCSTR optional -> "str"
; PathToSource : LPCSTR -> "str"
; SourceFile : LPCSTR -> "str"
; TargetPathFile : LPCSTR optional -> "str"
; Win32ErrorCode : DWORD -> "int"
; Style : DWORD -> "int"
; PathBuffer : LPSTR optional, out -> "var"
; PathBufferSize : DWORD -> "int"
; PathRequiredSize : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SETUPAPI.dll"
#cfunc global SetupCopyErrorA "SetupCopyErrorA" sptr, str, str, str, str, str, int, int, sptr, int, sptr
; res = SetupCopyErrorA(hwndParent, DialogTitle, DiskName, PathToSource, SourceFile, TargetPathFile, Win32ErrorCode, Style, varptr(PathBuffer), PathBufferSize, varptr(PathRequiredSize))
; hwndParent : HWND -> "sptr"
; DialogTitle : LPCSTR optional -> "str"
; DiskName : LPCSTR optional -> "str"
; PathToSource : LPCSTR -> "str"
; SourceFile : LPCSTR -> "str"
; TargetPathFile : LPCSTR optional -> "str"
; Win32ErrorCode : DWORD -> "int"
; Style : DWORD -> "int"
; PathBuffer : LPSTR optional, out -> "sptr"
; PathBufferSize : DWORD -> "int"
; PathRequiredSize : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。