SetupDiGetActualSectionToInstallA 函式 (setupapi.h)

  • 發行項

SetupDiGetActualSectionToInstall 函式會擷取適當的 INF DDInstall 區段，以在本機電腦上安裝裝置 INF 檔案時使用。

語法

WINSETUPAPI BOOL SetupDiGetActualSectionToInstallA(
  [in]            HINF   InfHandle,
  [in]            PCSTR  InfSectionName,
  [out, optional] PSTR   InfSectionWithExt,
  [in]            DWORD  InfSectionWithExtSize,
  [out, optional] PDWORD RequiredSize,
  [out, optional] PSTR   *Extension
);

參數

[in] InfHandle

包含 DDInstall 區段之 INF 檔案的句柄。

[in] InfSectionName

DDInstall 區段名稱的指標，如 INF Models 區段) 中所指定 (。 區段名稱的最大長度，以字元為單位為254。

[out, optional] InfSectionWithExt

要接收 DDInstall 區段名稱、其平臺延伸模組和 NULL 終止符之字元緩衝區的指標。 這是應該用於安裝的裝飾區段名稱。 如果此參數為 NULL，InfSectionWithExtSize 必須為零。 如果此參數為 NULL，函式會傳回 TRUE ，並將 RequiredSize 設定為大小，以字元為單位，這是傳回 DDInstall 區段名稱、其平臺延伸模組和終止 NULL 字元所需的字元。

[in] InfSectionWithExtSize

InfSectionWithExt 緩衝區的大小，以字元為單位。 如果 InfSectionWithExt 為 NULL，此參數必須為零。

[out, optional] RequiredSize

接收大小之變數的指標，以字元為單位，這是傳回 DDInstall 區段名稱、平臺延伸模組和終止 NULL 字元所需的指標。

[out, optional] Extension

變數的指標，接收 '.' 字元的指標，這個字元會標記 InfSectionWithExt 緩衝區中的延伸模塊開頭。 如果未提供 InfSectionWithExt 緩衝區或太小，則不會設定此參數。 如果不需要延伸模組的指標，請將此參數設定為 NULL 。

傳回值

如果函式成功，則會傳回 TRUE。 如果函式失敗，則會傳回 FALSE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式支援 DDInstall 區段名稱的擴充功能，這些名稱可用來指定裝置的 OS 特定和架構特定安裝行為。 如需這些延伸模組的相關信息，請參閱 建立多個平臺和操作系統的 INF 檔案。 SetupDiGetActualSectionToInstall 會以下列方式搜尋符合本機計算機的 DDInstall 區段名稱。

函式會先在指定的 INF 檔案中搜尋符合指定名稱的裝飾安裝區段名稱，並具有符合本機電腦的作業系統和處理器架構的擴展名。 例如，如果您指定 InstallSec 的區段名稱，函式會根據本機計算機的處理器架構，搜尋下列其中一個裝飾名稱：

  • 對於以 x86 處理器架構為基礎的計算機，函式會搜尋裝飾名稱 InstallSec.ntx86。
  • 對於以 x64 處理器架構為基礎的計算機，函式會搜尋裝飾名稱 InstallSec.ntamd64。
  • 對於以Itanium處理器架構為基礎的計算機，函式會搜尋裝飾名稱 InstallSec.ntia64。
如果函式找到名稱、操作系統和處理器架構的相符專案，它會終止搜尋並傳回對應的裝飾名稱。 如果函式找不到這類相符專案，函式會搜尋名稱為 InstallSec.NT 的區段。 如果函式找到 InstallSec.NT 的相符專案，它會終止搜尋並傳回此名稱。 如果函式找不到上述任一搜尋的相符專案，它會傳回 InstallSec，但不會驗證 INF 檔案是否包含名稱為 InstallSec 的安裝區段。

DDInstall 區段名稱會作為硬體和服務區段名稱的基底。 例如，如果找到的 DDInstall 區段名稱是 InstallSec.NTX86， 服務 區段名稱必須命名為 InstallSec.NTX86.Services。

驅動程式節點中指定的原始 DDInstall 區段名稱會寫入驅動程式登錄機碼的 InfSection 值專案。 找到的延伸模組會儲存在機碼中，作為 REG_SZ 值 InfSectionExt。 例如：

InfSection       : REG_SZ :    "InstallSec"
InfSectionExt    : REG_SZ :    ".NTX86"

如果未為指定的裝置資訊元素選取驅動程式，則會安裝 Null 驅動程式。 傳回時，裝置 SP_DEVINSTALL_PARAMS 結構中的旗標會指出系統應該重新啟動或重新啟動，以造成裝置啟動。

注意

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

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 setupapi.h (包括 Setupapi.h)
程式庫 Setupapi.lib

另請參閱

INF DDInstall 區段

SetupDiGetActualSectionToInstallEx

SetupDiInstallDevice