SetupCopyOEMInfA 函式 (setupapi.h)
[此函式可用於需求一節中所述的操作系統。 它在後續版本中可能會變更或無法使用。 安裝程式API不應再用於安裝應用程式。 請改用 Windows Installer 來開發應用程式安裝程式。 SetupAPI 會繼續用於安裝設備驅動器。]
SetupCopyOEMInf 函式會將指定的 .inf 檔案複製到 %windir%/Inf 目錄。
需要此函式的呼叫端具有系統管理許可權,否則函式會失敗。
語法
WINSETUPAPI BOOL SetupCopyOEMInfA(
[in] PCSTR SourceInfFileName,
[in] PCSTR OEMSourceMediaLocation,
[in] DWORD OEMSourceMediaType,
[in] DWORD CopyStyle,
[out, optional] PSTR DestinationInfFileName,
[in] DWORD DestinationInfFileNameSize,
[out, optional] PDWORD RequiredSize,
[out, optional] PSTR *DestinationInfFileNameComponent
);
參數
[in] SourceInfFileName
來源 .inf 檔案的完整路徑。 您應該使用以 Null 結尾的字串。 此路徑不應超過 大小MAX_PATH ,包括終止 的 NULL。
[in] OEMSourceMediaLocation
要儲存在先行編譯 .inf (.pnf) 的來源位置資訊。 此位置資訊是指定之來源媒體類型的特定資訊。 您應該使用以 Null 結尾的字串。 此路徑不應超過 大小MAX_PATH ,包括終止 的 NULL。
[in] OEMSourceMediaType
位置資訊所參考的來源媒體類型。 此參數可能是下列其中一個值。
[in] CopyStyle
指定 .inf 檔案如何複製到 .inf 目錄中。 您可以結合下列旗標。
值 | 意義 |
---|---|
|
在成功複製時刪除原始程序檔。 |
|
只有當此檔案已存在於 Inf 目錄中時,才會複製 。 此旗標可用來更新現有 .inf 的來源位置資訊。 |
|
只有當指定的檔案目前不存在於 Inf 目錄中時,才會複製 。 如果 .inf 目前存在,此 API 會失敗, 而且 GetLastError 會傳回ERROR_FILE_EXISTS。 在此情況下,現有的 .inf 檔案檔名會放在目的地 .inf 檔案信息輸出緩衝區的適當字段中。 |
|
指定的 .inf 檔案對應的目錄檔案會複製到 %windir%\Inf。 如果指定此旗標,如果 Inf 目錄中已有指定的 .inf 檔案,則會在成功傳回時輸入目的地檔名資訊。 |
[out, optional] DestinationInfFileName
緩衝區的指標,以在複製到 Inf 目錄時接收指派給緩衝區的 .inf 檔名。 如果指定,則緩衝區通常應該 MAX_PATH 長度。 如果指定SP_COPY_NOOVERWRITE旗標,且 SetupCopyOEMInf 函式失敗,且傳回碼為 ERROR_FILE_EXISTS,則此緩衝區會包含現有 .inf 檔案的名稱。 如果指定了SP_COPY_OEMINF_CATALOG_ONLY旗標,如果 .inf 檔案已存在於 Inf 目錄中,此緩衝區就會包含目的地 .inf 檔名。 否則,這個緩衝區會設定為空字串。 此參數可以是 Null。
[in] DestinationInfFileNameSize
如果未指定緩衝區, 則為 DestinationInfFileName 緩衝區的大小、以字元為單位,或為零。 如果指定 DestinationInfFileName ,且此緩衝區大小小於傳回目的地 .inf 檔名所需的大小, (包括完整路徑) ,則此函式會失敗。 在此情況下, GetLastError 會傳回ERROR_INSUFFICIENT_BUFFER。
[out, optional] RequiredSize
變數的指標,該變數會接收字元大小 (,) 儲存目的地 .inf 檔名所需的大小,包括終止 NULL。 如果指定了SP_COPY_OEMINF_CATALOG_ONLY旗標,則只有當 .inf 檔案已存在於 Inf 目錄中時,此變數才會收到字串長度。 否則,此變數會設定為零。 此參數可以是 Null。
[out, optional] DestinationInfFileNameComponent
成功傳回時所設定字串的指標 (或ERROR_FILE_EXISTS) 指向 DestinationInfFileName 參數中所儲存路徑的檔名元件開頭。 如果指定了SP_COPY_OEMINF_CATALOG_ONLY旗標, DestinationInfFileName 參數可能是空字串。 在此情況下,字元指標會在成功傳回時設定為 NULL 。 此參數可以是 Null。
傳回值
此函式會傳回 WINSETUPAPI BOOL。
備註
SetupCopyOEMInf 函式會將指定的 .inf 檔案複製到 %windir%\Inf 目錄中。 如果 SetupCopyOEMInf 發現指定的 .inf 檔案二進制映射已存在於同名的 Inf 目錄中,或是表單 OEM*.inf 的名稱,則 SetupCopyOEMInf 不會重新複製檔案。 當 SetupCopyOEMInf 複製檔案時,會將複製的檔案重新命名為 OEM*.inf。 提供的名稱是唯一的,無法預測。
SetupCopyOEMInf 會使用下列程序來判斷 .inf 檔案是否已存在於 Inf 目錄中:
會列舉所有名稱為 OEM*.inf 格式的 .inf 檔案,以及與指定 .inf 檔案具有相同檔案大小的任何檔案都會進行二進位比較。
Inf 目錄會搜尋 .inf 檔案的來源檔名。 如果同名的 .inf 檔案存在,且大小與指定 .inf 檔案的大小相同,則兩個檔案是二進位檔案,以判斷兩個檔案是否相同。
如果指定的 .inf 檔案已經存在,則會執行進一步檢查,以判斷指定的 .inf 檔案是否在其 [Version] 區段中包含 CatalogFile= 專案。 如果這麼做,則會使用 .inf 檔案的 %windir%\Inf 主要檔名搭配 “.cat” 擴展名來判斷是否已安裝目錄。 如果已安裝目錄,但與來源 .inf 相關聯的目錄不同,這不會被視為相符專案,而且列舉會繼續。 可以有多個相同的 .inf 檔案,其中包含 %windir%\Inf 目錄中的唯一目錄。 如果找不到現有的相符專案,.inf 和 .cat 檔案會以新的唯一名稱安裝。
未指定 CatalogFile= 專案的 OEM .inf 檔案在數位簽名驗證方面被視為無效。
如果 .inf 檔案必須複製到 %windir%\Inf 目錄,則會報告任何數位簽名驗證失敗。
如果 .inf 和 .cat 檔案已經存在,則會使用這些現有的檔名,而且檔案取代行為是以指定的 CopyStyle 旗標為基礎。 取代行為只會參考儲存在 .pnf 中的來源媒體資訊。 現有的 .inf、.pnf 和 .cat 檔案不會修改。
注意
setupapi.h 標頭會將 SetupCopyOEMInf 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | setupapi.h |
程式庫 | Setupapi.lib |
Dll | Setupapi.dll |
API 集合 | ext-ms-win-setupapi-classinstallers-l1-1-2 (於 Windows 10 10.0.14393 版中引進) |