SetupInstallFileA 函式 (setupapi.h)
[此函式可用於需求一節中所述的操作系統。 它在後續版本中可能會變更或無法使用。 安裝程式API不應再用於安裝應用程式。 請改用 Windows Installer 來開發應用程式安裝程式。 SetupAPI 會繼續用於安裝設備驅動器。]
SetupInstallFile 函式會安裝由 SetupFindXXXLine 所傳回的 INFCONTEXT 所指定的檔案，或由檔名和路徑明確指定。
如果複製檔案，此函式的呼叫端必須具有目標目錄中的寫入許可權。
語法
WINSETUPAPI BOOL SetupInstallFileA(
[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
);
參數
[in] InfHandle
包含 SourceDisksNames 和 SourceDisksFiles 區段之 INF 檔案句柄的選擇性指標。 例如，如果用戶的系統 (存在平臺特定區段，SourceDisksNames.x86 和 SourceDisksFiles.x86) ，將會使用平臺特定區段。 如果 InfContext 為 null 且 CopyStyle 包含SP_COPY_SOURCE_ABSOLUTE或SP_COPY_SOURCEPATH_ABSOLUTE， 則會忽略 InfHandle 。
[in] InfContext
INF 檔案中 [複製檔案] 區段中行內容的選擇性指標。 例程會在 InfHandle 的 SourceDisksFiles 區段中查閱此檔案，以取得檔案複製資訊。 如果未指定 InfHandle ， 則 SourceFile 必須是 。
[in] SourceFile
檔名的選擇性指標 (沒有要複製之檔案的路徑) 。 檔案會在SourceDisksFiles區段中查閱。 如果 InfContext 不是，則必須指定 SourceFile 參數。 如果指定 InfContext，則會忽略 SourceFile。
[in] SourcePathRoot
要複製之檔案的選擇性指標 (例如 A：\ 或 F：) 。 SourceDisksNames 區段中的路徑會附加至此路徑。 如果 CopyStyle 包含 SP_COPY_SOURCE_ABSOLUTE 旗標，則會忽略 SourcePathRoot 參數。
[in] DestinationName
只 (目標檔案的路徑) ，才能選擇檔名的指標。 此參數可以是 null，表示目標檔案的名稱應該與原始程式檔相同。 如果未指定 InfContext，DestinationName 會提供目標的完整路徑和檔案名。
[in] CopyStyle
旗標，控制檔案複製作業的行為。 這些旗標可能是下列值的組合。
| 值 | 意義 |
|---|---|
|
成功複製時，刪除來源檔案。 如果刪除作業失敗，則不會通知呼叫端。 |
|
只有在這麼做會覆寫目的地路徑上的檔案時，才會複製檔案。 如果目標不存在，函式會傳回 FALSE ，而 GetLastError 會傳回NO_ERROR。 |
|
檢查所複製的每個檔案，以查看其版本資源是否指出其版本是否與目標上現有的複本相同或不是更新版本。
在版本檢查期間使用的檔案版本資訊是在 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，則會忽略此旗標。 |
|
如果目標存在，的行為就像正在使用中一樣，並將檔案排入佇列，以便在下一次系統重新啟動時進行複製。 |
|
檢查目標檔案是否存在，如果存在，則不會覆寫檔案。 呼叫端不會收到通知。 |
|
檢查所複製的每個檔案，以查看其版本資源是否 (或非映射檔案的時間戳，) 指出它不是比目標上現有的複本還新。 如果複製的檔案不是較新的檔案，則不會複製檔案。 呼叫端不會收到通知。 函式會傳回 FALSE，而 GetLastError 會傳回NO_ERROR。 |
[in] CopyMsgHandler
回呼函式的選擇性指標，以通知檔案複製作業期間可能發生的各種條件。
[in] Context
呼叫端定義值的選擇性指標，這個值會傳遞為回呼函式的第一個參數。
傳回值
如果函式成功，則傳回值是非零值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
如果 GetLastError 傳回NO_ERROR，則檔案複製作業尚未完成。 因為檔案複製作業不必要，或檔案回呼函式傳回 FALSE，所以可能尚未複製檔案。
備註
如果 UNC 目錄指定為檔案安裝的目標目錄，您必須先確定它存在，再呼叫 SetupInstallFile。 安裝程式函式不會檢查是否存在，也不會建立 UNC 目錄。 如果目標 UNC 目錄不存在，則檔案安裝將會失敗。
注意
setupapi.h 標頭會將 SetupInstallFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | setupapi.h |
| 程式庫 | Setupapi.lib |
| Dll | Setupapi.dll |