SetupInstallFileExW 関数 (setupapi.h)
[この機能は、「要件」セクションに示されているオペレーティング システムで使用できます。 今後のバージョンでは変更されるか、利用できなくなる場合もあります。 SetupAPI は、アプリケーションのインストールに使用されなくなりました。 代わりに、アプリケーション インストーラーを開発するために Windows インストーラーを使用します。 SetupAPI は、デバイス ドライバーのインストールに引き続き使用されます。]
SetupInstallFileEx 関数は、SetupFindXXXLine によって返される INFCONTEXT によって、またはファイル名とパス情報によって明示的に指定されたファイルをインストールします。 この関数は SetupInstallFile と同じですが、ファイルが使用中かどうかを示す BOOL が返される点が除きます。
ファイルがコピーされる場合、この関数の呼び出し元は、ターゲット ディレクトリに書き込む権限を持っている必要があります。
構文
WINSETUPAPI BOOL SetupInstallFileExW(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCWSTR SourceFile,
[in] PCWSTR SourcePathRoot,
[in] PCWSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_W CopyMsgHandler,
[in] PVOID Context,
[out] PBOOL FileWasInUse
);
パラメーター
[in] InfHandle
SourceDisksNames セクションと SourceDisksFiles セクションを含む INF ファイルへのハンドルへのオプションのポインター。 ユーザーのシステム (SourceDisksNames.x86 や SourceDisksFiles.x86 など) にプラットフォーム固有のセクションが存在する場合は、プラットフォーム固有のセクションが使用されます。 InfContext が指定されておらず、CopyStyle にSP_COPY_SOURCE_ABSOLUTEまたはSP_COPY_SOURCEPATH_ABSOLUTEが含まれている場合、InfHandle は無視されます。
[in] InfContext
INF ファイルの [ファイルのコピー] セクションの行のコンテキストへのオプションのポインター。 ルーチンは、 InfHandle の SourceDisksFiles セクションでこのファイルを検索して、ファイル コピー情報を取得します。 InfContext が指定されていない場合は、SourceFile を指定する必要があります。
[in] SourceFile
コピーするファイルのファイル名 (パスなし) へのオプションのポインター。 ファイルは、SourceDisksFiles セクションで検索されます。 InfContext が指定されていない場合は、SourceFile パラメーターを指定する必要があります。 ただし、InfContext が指定されている場合、SourceFile は無視されます。
[in] SourcePathRoot
コピーするファイルのルート パスへの省略可能なポインター (A:\ や F:など)。 SourceDisksNames セクションのパスは、このパスに追加されます。 CopyStyle に SP_COPY_SOURCE_ABSOLUTE フラグが含まれている場合、SourcePathRoot パラメーターは無視されます。
[in] DestinationName
コピーしたファイルの新しい名前へのオプションのポインター。 InfContext が指定されている場合、DestinationName はターゲット ファイルのファイル名のみを指定します (パスなし)。 ターゲット ファイルの名前がソース ファイルと同じである必要があることを示すには、このパラメーターに NULL を 指定できます。 InfContext が指定されていない場合、DestinationName はターゲットの完全なターゲット パスとファイル名を提供します。
[in] CopyStyle
ファイル コピー操作の動作を制御するフラグ。
これらのフラグは、次の値の組み合わせにすることができます。
| 値 | 意味 |
|---|---|
|
コピーが正常に完了したら、ソース ファイルを削除します。 削除が失敗した場合、呼び出し元には通知されません。 |
|
コピー先のパスにあるファイルが上書きされる場合にのみ、ファイルをコピーします。 |
|
コピーされる各ファイルを調べて、そのバージョン リソースがターゲット上の既存のコピーと同じバージョンか新しくないか確認します。
バージョン チェック中に使用されるファイル バージョン情報は、バージョン関数によって入力された、VS_FIXEDFILEINFO構造体の dwFileVersionMS メンバーと dwFileVersionLS メンバーで指定されています。 いずれかのファイルにバージョン リソースがない場合、または同じバージョン情報がある場合、ソース ファイルは新しいと見なされます。 ソース ファイルが新しくないか、バージョンが等しくない場合に CopyMsgHandler が指定されている場合、呼び出し元に通知され、コピーを取り消すことができます。 CopyMsgHandler が指定されていない場合、ファイルはコピーされません。 |
|
コピーされる各ファイルを調べて、そのバージョン リソースがターゲット上の既存のコピーよりも新しくないことを示しているかどうかを確認します。 ソース ファイルが新しいが、バージョンが既存のターゲットと等しくない場合は、ファイルがコピーされます。 |
|
ターゲット ファイルが存在するかどうかを確認し、存在する場合は、コピーを拒否する可能性がある呼び出し元に通知します。 CopyMsgHandler が指定されていない場合、ファイルは上書きされません。 |
|
ファイルを圧縮解除しないでください。 このフラグが設定されている場合、ターゲット ファイルにはソース名の圧縮されていない形式が指定されません (該当する場合)。 たとえば、"f:\x86\cmd.ex_" を "\\install\temp" にコピーすると、ターゲット ファイルは "\\install\temp\cmd.ex_" になります。 SP_COPY_NODECOMP フラグが指定されていない場合、ファイルは圧縮解除され、ターゲットは "\\install\temp\cmd.exe" と呼ばれます。 DestinationName のファイル名部分を指定すると、削除され、ソース ファイルのファイル名に置き換えられます。 SP_COPY_NODECOMPを指定すると、言語やバージョン情報を確認できません。 |
|
コピーされる各ファイルを調べて、その言語がターゲット上の既存のファイルの言語と異なるかどうかを確認します。 その場合、 CopyMsgHandler を指定すると、呼び出し元に通知が送信され、コピーを取り消すことができます。 CopyMsgHandler が指定されていない場合、ファイルはコピーされません。 |
|
SourceFile は完全なソース パスです。 INF ファイルの SourceDisksNames セクションで検索しないでください。 |
|
SourcePathRoot は、ソース ファイルの完全なパス部分です。 ファイルが配置されているソース メディアの INF ファイルの SourceDisksNames セクションで指定された相対ソースを無視します。 SP_COPY_SOURCE_ABSOLUTEが指定されている場合、このフラグは無視されます。 |
|
ターゲットが存在する場合は、使用中のように動作し、次のシステム再起動時にコピーするファイルをキューに入れます。 |
|
コピー操作中にファイルが使用されていた場合は、システムの再起動が必要であることをユーザーに警告します。 |
|
ファイルをスキップするオプションをユーザーに与えないでください。 |
|
ターゲット ファイルが存在するかどうかを確認します。存在する場合は、ファイルは上書きされません。 呼び出し元には通知されません。 |
|
コピーされる各ファイルを調べて、そのバージョン リソース (またはイメージ以外のファイルのタイム スタンプ) が、ターゲット上の既存のコピーよりも新しくないことを示しているかどうかを確認します。 コピーされるファイルが新しくない場合、ファイルはコピーされません。 呼び出し元には通知されません。 |
|
ユーザーがファイルをスキップしようとすると、ファイルをスキップするとインストールに影響する可能性があることを警告します。 (システム クリティカルなファイルに使用されます)。 |
[in] CopyMsgHandler
ファイルのコピー中に発生する可能性のあるさまざまな条件を通知するコールバック関数へのオプションのポインター。
[in] Context
コールバック関数の最初のパラメーターとして渡される呼び出し元定義値へのポインター。
[out] FileWasInUse
この関数がファイルが使用中かどうかを示すフラグを返す変数へのポインター。 このパラメーターは必須です。
戻り値
関数が成功した場合、戻り値は 0 以外の値になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
GetLastError がNO_ERRORを返した場合、ファイルのコピー操作は完了していません。 ファイルのコピー操作が不要であったか、ファイル コールバック関数が FALSE を返したため、ファイルがコピーされていない可能性があります。
注釈
この API は、通常、使用されている可能性が高い新しいバージョンのシステム ファイルをインストールするときに使用されます。 ファイルが使用されていたかどうかを示す BOOL 値が更新されます。 ファイルが使用中の場合、ファイルのコピー操作はシステムが再起動されるまで延期されます。
UNC ディレクトリがファイル インストールのターゲット ディレクトリとして指定されている場合は、 SetupInstallFileEx を呼び出す前に、UNC ディレクトリが存在することを確認する必要があります。 セットアップ関数は、 の存在をチェックせず、UNC ディレクトリを作成しません。 ターゲット UNC ディレクトリが存在しない場合、ファイルのインストールは失敗します。
注意
setupapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupInstallFileEx を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | setupapi.h |
| Library | Setupapi.lib |
| [DLL] | Setupapi.dll |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示