SetupInstallFileA 函式（setupapi.h）

發行項
11/20/2024

[此函式可用於需求一節所指出的作業系統。後續版本可能會變更或無法使用。安裝程式API 不應該再用於安裝應用程式。請改用 Windows Installer 來開發應用程式安裝程式。 SetupAPI 會繼續用於安裝設備驅動器。]

SetupInstallFile 函式會安裝由 SetupFindXXXLine 所傳回的 INFCON TEXT 所指定的檔案，或由檔名和路徑明確傳回。

如果複製檔案，此函式的呼叫端必須具有目標目錄中的寫入許可權。

語法

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

旗標，控制檔案複製作業的行為。這些旗標可能是下列值的組合。

價值	意義
SP_COPY_DELETESOURCE	成功複製時，刪除來源檔案。如果刪除作業失敗，則不會通知呼叫端。
SP_COPY_REPLACEONLY	只有在這樣做會覆寫目的地路徑上的檔案時，才會複製檔案。如果目標不存在，函式會傳回 FALSE ，而 getLastError 會傳回NO_ERROR。
SP_COPY_NEWER_OR_SAME	檢查要複製的每個檔案，以查看其版本資源是否表示其版本是否為與目標上現有復本相同的版本或更新版本。在版本檢查期間所使用的檔案版本資訊，是在 dwFileVersionMS 和 dwFileVersionLSVS_FIXEDFILEINFO 結構的成員中所指定，如版本函式所填入。如果其中一個檔案沒有版本資源，或它們具有相同的版本資訊，則來源檔案會被視為較新。如果原始程式檔在版本中不是較新或相等，而且已指定 copyMsgHandler ，呼叫端會收到通知，而且可能會取消複製作業。如果未指定 CopyMsgHandler，則不會複製檔案。
SP_COPY_NEWER_ONLY	檢查要複製的每個檔案，以查看其版本資源是否表示它不是比目標上現有的複本還新。如果來源檔案較新，但不等於現有目標的版本，則會複製該檔案。
SP_COPY_NOOVERWRITE	檢查目標檔案是否存在，如果是的話，請通知可能否決該複本的呼叫端。如果未指定 copyMsgHandler ，則不會覆寫檔案。
SP_COPY_NODECOMP	請勿解壓縮檔案。設定此旗標時，目標檔案不會提供來源名稱的未壓縮形式（如果適當的話）。例如，將 F：\x86\cmd.ex_ 複製到 \\安裝\temp 會導致目標檔案 \\install\temp\cmd.ex_。如果未指定SP_COPY_NODECOMP旗標，則會解壓縮檔案，並將目標稱為 \\install\temp\cmd.exe。 DestinationName的檔名部分，如果指定，則會移除並以原始程式檔的檔名取代。指定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_FORCE_NOOVERWRITE	檢查目標檔案是否存在，如果存在，則不會覆寫檔案。呼叫端未收到通知。
SP_COPY_FORCE_NEWER	檢查要複製的每個檔案，以查看其版本資源（或非映像檔案的時間戳）是否表示它不比目標上的現有復本還新。如果複製的檔案不是較新檔案，則不會複製檔案。呼叫端未收到通知。函式會傳回 FALSE，而 getLastError 會傳回NO_ERROR。

[in] CopyMsgHandler

回呼函式的選擇性指標，可通知檔案複製作業期間可能發生的各種情況。

[in] Context

回呼函式的第一個參數傳遞之呼叫端定義值的選擇性指標。

傳回值

如果函式成功，則傳回值是非零值。

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果 GetLastError 傳回NO_ERROR，則檔案複製作業尚未完成。因為不需要檔案複製作業，或因為檔案回呼函式傳回 FALSE，因此可能尚未複製檔案。

言論

如果 UNC 目錄指定為檔案安裝的目標目錄，您必須先確定該目錄存在，再呼叫 SetupInstallFile。安裝程式函式不會檢查是否存在，也不會建立 UNC 目錄。如果目標 UNC 目錄不存在，檔案安裝將會失敗。

注意

setupapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 SetupInstallFile 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	setupapi.h
連結庫	Setupapi.lib
DLL	Setupapi.dll