SetupInstallFileExA 関数 (setupapi.h)

  • [アーティクル]

[この機能は、[要件] セクションに示されているオペレーティング システムで使用できます。 今後のバージョンでは変更されるか、利用できなくなる場合もあります。 SetupAPI は、アプリケーションのインストールに使用されなくなりました。 代わりに、Windows インストーラーを使用してアプリケーション インストーラーを開発します。 SetupAPI は、引き続きデバイス ドライバーのインストールに使用されます。

SetupInstallFileEx 関数は、SetupFindXXXLine によって返される INFCONTEXT またはファイル名とパス情報によって明示的に指定されたファイルをインストールします。 この関数は SetupInstallFile と同じですが、ファイルが使用されていたかどうかを示す BOOL が返される点が除きます。

ファイルがコピーされる場合、この関数の呼び出し元には、ターゲット ディレクトリに書き込む権限が必要です。

構文

WINSETUPAPI BOOL SetupInstallFileExA(
  [in]  HINF                InfHandle,
  [in]  PINFCONTEXT         InfContext,
  [in]  PCSTR               SourceFile,
  [in]  PCSTR               SourcePathRoot,
  [in]  PCSTR               DestinationName,
  [in]  DWORD               CopyStyle,
  [in]  PSP_FILE_CALLBACK_A 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

ファイル コピー操作の動作を制御するフラグ。

これらのフラグは、次の値の組み合わせにすることができます。

値 意味
SP_COPY_DELETESOURCE
 コピーが正常に完了したら、ソース ファイルを削除します。 削除が失敗した場合、呼び出し元には通知されません。
SP_COPY_REPLACEONLY
 コピー先のパスにあるファイルが上書きされる場合にのみ、ファイルをコピーします。
SP_COPY_NEWER_OR_SAME
 コピーされる各ファイルを調べて、そのバージョン リソースが、ターゲット上の既存のコピーと同じバージョンか新しくないかのどちらかであることを示しているかどうかを確認します。

バージョン チェック時に使用されるファイル バージョン情報は、バージョン関数で入力されたVS_FIXEDFILEINFO構造体の dwFileVersionMS メンバーと dwFileVersionLS メンバーで指定されています。 いずれかのファイルにバージョン リソースがない場合、または同じバージョン情報がある場合、ソース ファイルは新しいと見なされます。

ソース ファイルが新しくないか、バージョンが等しくなく、 CopyMsgHandler が指定されている場合、呼び出し元に通知が送信され、コピーが取り消される可能性があります。 CopyMsgHandler が指定されていない場合、ファイルはコピーされません。
SP_COPY_NEWER_ONLY
 コピーされる各ファイルを調べて、そのバージョン リソースがターゲット上の既存のコピーよりも新しくないことを示しているかどうかを確認します。 ソース ファイルが新しいが、既存のターゲットとバージョンが等しくない場合は、ファイルがコピーされます。
SP_COPY_NOOVERWRITE
 ターゲット ファイルが存在するかどうかを確認し、存在する場合は、コピーを拒否する可能性がある呼び出し元に通知します。 CopyMsgHandler が指定されていない場合、ファイルは上書きされません。
SP_COPY_NODECOMP
 ファイルを展開しないでください。 このフラグが設定されている場合、ターゲット ファイルにはソース名の圧縮されていない形式が指定されません (該当する場合)。 たとえば、"f:\x86\cmd.ex_" を "\\install\temp" にコピーすると、ターゲット ファイルは "\\install\temp\cmd.ex_" になります。 SP_COPY_NODECOMP フラグが指定されていない場合、ファイルは圧縮解除され、ターゲットは "\\install\temp\cmd.exe" と呼ばれます。 DestinationName の filename 部分が指定されている場合、削除され、ソース ファイルのファイル名に置き換えられます。 SP_COPY_NODECOMPを指定すると、言語やバージョン情報を確認できません。
SP_COPY_LANGUAGEAWARE
 コピーされる各ファイルを調べて、その言語がターゲットに既に存在する既存のファイルの言語と異なるかどうかを確認します。 その場合、 CopyMsgHandler を指定すると、呼び出し元に通知され、コピーを取り消すことができます。 CopyMsgHandler が指定されていない場合、ファイルはコピーされません。
SP_COPY_SOURCE_ABSOLUTE
 SourceFile は完全なソース パスです。 INF ファイルの SourceDisksNames セクションで検索しないでください。
SP_COPY_SOURCEPATH_ABSOLUTE
 SourcePathRoot は、ソース ファイルの完全なパス部分です。 ファイルが配置されているソース メディアの INF ファイルの SourceDisksNames セクションで指定された相対ソースを無視します。 SP_COPY_SOURCE_ABSOLUTEが指定されている場合、このフラグは無視されます。
SP_COPY_FORCE_IN_USE
 ターゲットが存在する場合は、使用中のように動作し、次のシステム再起動時にコピー用にファイルをキューに入れます。
SP_COPY_IN_USE_NEEDS_REBOOT
 コピー操作中にファイルが使用されていた場合は、システムの再起動が必要であることをユーザーに警告します。
SP_COPY_NOSKIP
 ファイルをスキップするオプションをユーザーに与えないでください。
SP_COPY_FORCE_NOOVERWRITE
 ターゲット ファイルが存在するかどうかを確認します。存在する場合は、ファイルは上書きされません。 呼び出し元には通知されません。
SP_COPY_FORCE_NEWER
 コピーされる各ファイルを調べて、そのバージョン リソース (またはイメージ以外のファイルのタイム スタンプ) が、ターゲット上の既存のコピーよりも新しくないことを示しているかどうかを確認します。 コピーするファイルが新しくない場合、ファイルはコピーされません。 呼び出し元には通知されません。
SP_COPY_WARNIFSKIP
 ユーザーがファイルをスキップしようとすると、ファイルをスキップするとインストールに影響する可能性があることを警告します。 (システム クリティカルなファイルに使用されます)。

[in] CopyMsgHandler

ファイルコピー中に発生する可能性のあるさまざまな条件を通知するコールバック関数へのオプションのポインター。

[in] Context

コールバック関数の最初のパラメーターとして渡される呼び出し元定義値へのポインター。

[out] FileWasInUse

この関数がファイルが使用中かどうかを示すフラグを返す変数へのポインター。 このパラメーターは必須です。

戻り値

関数が成功した場合、戻り値は 0 以外の値になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

GetLastError がNO_ERRORを返した場合、ファイルのコピー操作は完了していません。 ファイルのコピー操作が不要であったか、ファイル コールバック関数が FALSE を返したため、ファイルがコピーされていない可能性があります。

注釈

この API は、通常、使用される可能性が高い新しいバージョンのシステム ファイルをインストールするときに使用されます。 ファイルが使用されていたかどうかを示す BOOL 値が更新されます。 ファイルが使用中の場合、ファイルのコピー操作はシステムが再起動されるまで延期されます。

UNC ディレクトリがファイル インストールのターゲット ディレクトリとして指定されている場合は、 SetupInstallFileEx を呼び出す前に、そのディレクトリが存在することを確認する必要があります。 セットアップ関数は、 の存在をチェックせず、UNC ディレクトリを作成しません。 ターゲット UNC ディレクトリが存在しない場合、ファイルのインストールは失敗します。

注意

setupapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupInstallFileEx を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー setupapi.h
Library Setupapi.lib
[DLL] Setupapi.dll

関連項目

関数

概要

SetupCloseFileQueue

SetupCommitFileQueue

SetupInstallFile

SetupOpenFileQueue

SetupPromptReboot

SetupQueueCopy