SetupInstallFileExA 函式 (setupapi.h)
[此函式可用於需求一節中所述的操作系統。 它在後續版本中可能會變更或無法使用。 安裝程式API不應再用於安裝應用程式。 請改用 Windows Installer 來開發應用程式安裝程式。 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
旗標，控制檔案複製作業的行為。
這些旗標可以是下列值的組合。
| 值 | 意義 |
|---|---|
|
成功複製時刪除來源檔案。 如果刪除失敗，則不會通知呼叫端。 |
|
只有在這麼做會覆寫目的地路徑上的檔案時，才複製檔案。 |
|
檢查正在複製的每個檔案，以查看其版本資源是否表示其版本是否與目標上現有的複本相同或不是更新版本。
在版本檢查期間使用的檔案版本資訊是在 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
此函式傳回旗標的變數指標，指出檔案是否正在使用中。 此為必要參數。
傳回值
如果函式成功，則傳回值是非零值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
如果 GetLastError 傳回NO_ERROR，則檔案複製作業尚未完成。 因為檔案複製作業不必要，或檔案回呼函式傳回 FALSE，所以可能尚未複製檔案。
備註
安裝可能正在使用的新版本系統檔案時，通常會使用此 API。 它會更新 BOOL 值，指出檔案是否正在使用中。 如果檔案正在使用中，則會延後檔案複製作業，直到系統重新啟動為止。
如果 UNC 目錄指定為檔案安裝的目標目錄，您必須先確定它存在，才能呼叫 SetupInstallFileEx。 安裝程式函式不會檢查 是否存在，而且不會建立 UNC 目錄。 如果目標 UNC 目錄不存在，則檔案安裝會失敗。
注意
setupapi.h 標頭會將 SetupInstallFileEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | setupapi.h |
| 程式庫 | Setupapi.lib |
| Dll | Setupapi.dll |