INF AddInterface 指示詞

發行項
02/07/2024

您可以在 INF DDInstall.Interfaces 區段中指定一或多個 AddInterface 指示詞。此指示詞會安裝匯出至較高層級元件之裝置介面類別的裝置特定支援，例如其他驅動程式或應用程式。指示詞通常會參考 add-interface-section ，這會為裝置介面類別的裝置特定實例設定登錄資訊。

[DDInstall.Interfaces]
  
AddInterface={InterfaceClassGUID} [,[reference-string] [,[add-interface-section][,flags]]]

導出的裝置介面類別可以是系統定義的裝置介面類別之一，例如核心串流所定義的類別，或是 INF InterfaceInstall32 區段所指定的新裝置介面類別。

項目

InterfaceClassGUID
指定識別裝置介面類別的 GUID 值。這可以表示為{nn---- nn} 格式的明確 GUID 值，或在 INF 檔案的 Strings 區段中定義為 “{----nn nn}” 的 %strkey% 令牌。

如需如何建立 GUID 的詳細資訊，請參閱在驅動程式中使用 GUID。如需系統定義的介面類別 GUIDS，請參閱適當的標頭，例如核心串流介面 GUID 的 Ks.h 。

reference-string
這個選擇性值與指定介面類別的裝置特定實例相關聯，可以表示為「引號字串」或 INF Strings 區段中定義的 %strkey% 標記。

PnP 函式和篩選驅動程式通常會從其 INF 檔案中的 AddInterface= 專案省略此值。 swenum 驅動程式會使用 reference-string 作為軟體裝置的佔位符，這些裝置是使用單一介面類別的多個實例視需要建立的軟體裝置。您可以在 INF 專案中指定相同的 InterfaceClassGUID 值，其中包含兩個或多個唯一 參考字串s。因為 I/O 管理員會在開啟介面實例名稱時，將 參考字串 值當做介面實例名稱的路徑元件傳遞，所以已安裝的驅動程式可以在單一裝置的相同類別的介面實例之間區分。

add-interface-section
參考 INF 檔案中其他地方的區段名稱。這通常包含 INF AddReg 指示詞 ，可設定匯出此裝置介面類別驅動程式支援的登錄專案。如需詳細資訊，請參閱下列一節。

flags
如果指定，此項目必須是零。

備註

如果尚未安裝指定的 {InterfaceClassGUID} 所識別的裝置介面類別，則系統安裝程式程式代碼會在系統中安裝該類別。任何安裝新類別的 INF 檔案也可能有 INF InterfaceInstall32 區段。本節包含指定的 {InterfaceClassGUID} ，並參考 介面-install-section ，該區段會設定該類別的介面特定安裝作業。

若要啟用裝置介面類別的實例以供較高層級元件使用運行時間，設備驅動器必須先呼叫 IoRegisterDeviceInterface ，才能擷取裝置介面實例的符號連結名稱以啟用。通常，PnP 函式或篩選驅動程式會從其 AddDevice 例程進行此呼叫。若要啟用 INF 中布建的裝置介面實例，設備驅動器必須在呼叫 IoRegisterDeviceInterface 時，提供 INF 中指定的 {InterfaceClassGUID} 和參考字元串。驅動程式接著會呼叫 IoSetDeviceInterfaceState ，以使用 IoRegisterDeviceInterface所傳回的符號連結名稱來啟用介面。

INF DDInstall.Interfaces 區段中的每個 AddInterface 指示詞都可以參考 INF 檔案中其他位置的 INF-writer-defined add-interface-section。每個 INF 寫入器定義的區段名稱在 INF 檔案內必須是唯一的，而且必須遵循定義區段名稱的一般規則。如需這些規則的詳細資訊，請參閱 INF 檔案的一般語法規則。

AddInterface 指示詞所參考的 add-interface-section 具有下列形式：

[add-interface-section]
 
AddReg=add-registry-section[, add-registry-section]...
[AddProperty=add-property-section[, add-property-section] ...]  (Windows Vista and later versions of Windows)
[DelReg=del-registry-section[, del-registry-section] ...]
[DelProperty=del-property-section[, del-property-section] ...]  (Windows Vista and later versions of Windows)
[BitReg=bit-registry-section[,bit-registry-section] ...]
[CopyFiles=@filename | file-list-section[,file-list-section]...]
[DelFiles=file-list-section[,file-list-section]...]
[RenFiles=file-list-section[,file-list-section]...]
[UpdateInis=update-ini-section[, update-ini-section] ...]
[UpdateIniFields=update-inifields-section[, update-inifields-section] ...]
[Ini2Reg=ini-to-registry-section[, ini-to-registry-section] ...]

從 Windows Vista 開始，您可以在 add-interface 區段中加入 INF AddProperty 指示詞 ，來設定裝置介面屬性。您也可以在 add-interface 區段中加入 INF DelProperty 指示詞來刪除裝置介面屬性。不過，您應該只使用 AddProperty 或 DelProperty 指示詞來修改 Windows Vista 或更新版本的 Windows 操作系統的裝置介面屬性。對於在 Windows Server 2003、Windows XP 或 Windows 2000 上引進且具有對應登錄值專案的裝置介面屬性，您應該繼續使用 INF AddReg 指示詞 和 INF DelReg 指示 詞來設定和刪除裝置介面屬性。這些指導方針適用於系統定義的屬性和自定義屬性。如需如何使用 AddProperty 指示詞和 DelProperty 指示詞的詳細資訊，請參閱使用 INF AddProperty 指示詞和 INF DelProperty 指示詞。

一般而言， add-interface-section 只包含 INF AddReg 指示詞 ，接著會參考單一 add-registry-section。 add-registry-section 可用來將設備驅動器所支援介面的信息儲存在登錄中，以供更高層級的驅動程式和應用程式後續使用。

add-interface-section 內參考的 add-registry-section 專屬於裝置、驅動程式和介面的實例。它可能會有一個值專案，其定義導出裝置介面實例的易記名稱，讓較高層級的元件可以在使用者介面中依其易記名稱來參考該介面。

這類 add-registry-section 區段中指定的 HKR 會指定裝置介面的運行時間可存取狀態登錄機碼。驅動程式可以在運行時間存取儲存在此登錄機碼中的狀態，方法是呼叫 IoOpenDeviceInterfaceRegistryKey 來擷取狀態登錄機碼的 HANDLE。使用者模式元件可以呼叫 CM_Open_Device_Interface_Key 來查詢狀態。

範例

此範例顯示 DDInstall 的一些擴充。支援系統定義核心串流介面之特定音訊裝置的介面區段。

; ...
[ESS6881.Device.Interfaces]
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_CAPTURE%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_CAPTURE%,%KSNAME_UART%,WDM.Interface.UART

[ESSAud.Interface.Wave]
AddReg=ESSAud.Interface.Wave.AddReg

[ESSAud.Interface.Wave.AddReg]
HKR,,CLSID,,%Proxy.CLSID%
HKR,,FriendlyName,,%ESSAud.Wave.szPname%
; ... 
[WDM.Interface.UART]
AddReg=WDM.Interface.UART.AddReg

[WDM.Interface.UART.AddReg]
HKR,,CLSID,,%Proxy.CLSID%
HKR,,FriendlyName,,%WDM.UART.szPname%
; ...
[Strings]
KSCATEGORY_AUDIO="{6994ad04-93ef-11d0-a3cc-00a0c9223196}"
KSCATEGORY_RENDER="{65e8773e-8f56-11d0-a3b9-00a0c9223196}"
KSCATEGORY_CAPTURE="{65e8773d-8f56-11d0-a3b9-00a0c9223196}"
; ...
KSNAME_WAVE="Wave"
KSNAME_UART="UART"
; ...
Proxy.CLSID="{17cca71b-ecd7-11d0-b908-00a0c9223196}"
; ... 
ESSAud.Wave.szPname="ESS AudioDrive" 
; ...