INF AddInterface-Direktive

Artikel
02/07/2024

Eine oder mehrere AddInterface-Anweisungen können in einem INF DDInstall.Interfaces-Abschnitt angegeben werden. Mit dieser Anweisung wird gerätespezifische Unterstützung für Geräteschnittstellenklassen installiert, die in Komponenten höherer Ebene exportiert werden, z. B. andere Treiber oder Anwendungen. Die Direktive verweist in der Regel auf einen add-interface-section, der Registrierungsinformationen für die gerätespezifische instance der Geräteschnittstellenklasse einrichtt.

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

Eine exportierte Geräteschnittstellenklasse kann eine der systemdefinierte Geräteschnittstellenklassen sein, z. B. solche, die durch Kernelstreaming definiert werden, oder eine neue Geräteschnittstellenklasse, die durch einen INF InterfaceInstall32-Abschnitt angegeben wird.

Einträge

InterfaceClassGUID
Gibt den GUID-Wert an, der die Geräteschnittstellenklasse identifiziert. Dies kann als expliziter GUID-Wert des Formulars {nnnnnnnnn-nnnn-nnn-nn-} oder als %strkey ausgedrückt werden. % token defined to "{nnnnnnn-nnnnn-nnn--}in aStrings section of the INF file.

Weitere Informationen zum Erstellen einer GUID finden Sie unter Verwenden von GUIDs in Treibern. Für die systemdefinierte Schnittstellenklasse GUIDS finden Sie den entsprechenden Header, z . B. Ks.h für die Kernel-Streaming-Schnittstellen-GUIDs.

Verweiszeichenfolge
Dieser optionale Wert, der dem gerätespezifischen instance der angegebenen Schnittstellenklasse zugeordnet ist, kann entweder als "Anführungszeichenzeichenfolge" oder als %strkey%-Token ausgedrückt werden, das in einem INF-Zeichenfolgenabschnitt definiert ist.

PnP-Funktions- und Filtertreiber lassen diesen Wert in der Regel aus den AddInterface=- Einträgen in ihren INF-Dateien aus. Eine Verweiszeichenfolge wird vom Swenum-Treiber als Platzhalter für Softwaregeräte verwendet, die bei Bedarf mithilfe mehrerer Instanzen einer einzelnen Schnittstellenklasse erstellt werden. Derselbe InterfaceClassGUID-Wert kann in INF-Einträgen mit mindestens zwei eindeutigen Verweiszeichenfolgenangegeben werden. Da der E/A-Manager den Verweiszeichenfolgenwert als Pfadkomponente der Schnittstelle instance den Namen der Schnittstelle übergibt, wenn sie geöffnet wird, kann der installierte Treiber zwischen Schnittstelleninstanzen derselben Klasse für ein einzelnes Gerät unterscheiden.

add-interface-section
Verweist auf den Namen eines Abschnitts an einer anderen Stelle in der INF-Datei. Dies enthält in der Regel eine INF AddReg-Anweisung zum Einrichten der Registrierungseinträge, die die Unterstützung dieser Geräteschnittstellenklasse durch den Treiber exportieren. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .

flags
Wenn angegeben, muss dieser Eintrag 0 sein.

Hinweise

Wenn die durch eine angegebene {InterfaceClassGUID} identifizierte Geräteschnittstellenklasse noch nicht installiert ist, installiert der Systemeinrichtungscode diese Klasse im System. Jede INF-Datei, die eine neue Klasse installiert, kann auch über einen INF InterfaceInstall32-Abschnitt verfügen. Dieser Abschnitt enthält die angegebene {InterfaceClassGUID} und verweist auf einen Abschnitt interface-install-section , in dem schnittstellenspezifische Installationsvorgänge für diese Klasse eingerichtet werden.

Um eine instance einer Geräteschnittstellenklasse für die Laufzeitnutzung durch Komponenten höherer Ebene zu aktivieren, muss ein Gerätetreiber zuerst IoRegisterDeviceInterface aufrufen, um den symbolischen Linknamen der Zu aktivierenden Geräteschnittstelle abzurufen, instance. Normalerweise führt eine PnP-Funktion oder ein Filtertreiber diesen Aufruf aus der AddDevice-Routine aus. Zum Aktivieren von Instanzen von Geräteschnittstellen, die im INF bereitgestellt werden, muss der Gerätetreiber die {InterfaceClassGUID} und die Verweiszeichenfolge bereitstellen, die beim Aufrufen von IoRegisterDeviceInterface im INF angegeben sind. Der Treiber ruft dann IoSetDeviceInterfaceState auf, um die Schnittstelle mithilfe des symbolischen Linknamens zu aktivieren, der von IoRegisterDeviceInterface zurückgegeben wird.

Jede AddInterface-Anweisung in einem INF DDInstall.Interfaces-Abschnitt kann an anderer Stelle in der INF-Datei auf einen inF-writer-defined add-interface-section verweisen. Jeder vom INF-Writer definierte Abschnittsname muss innerhalb der INF-Datei eindeutig sein und den allgemeinen Regeln zum Definieren von Abschnittsnamen entsprechen. Weitere Informationen zu diesen Regeln finden Sie unter Allgemeine Syntaxregeln für INF-Dateien.

Ein add-interface-section , auf den von der AddInterface-Anweisung verwiesen wird, weist die folgende Form auf:

[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] ...]

Ab Windows Vista können Sie Geräteschnittstelleneigenschaften festlegen, indem Sie INF AddProperty-Anweisungen in einen Add-Interface-Abschnitt einschließen. Sie können Geräteschnittstelleneigenschaften auch löschen, indem Sie INF DelProperty-Anweisungen in einen Add-Interface-Abschnitt einschließen. Sie sollten jedoch AddProperty - oder DelProperty-Direktiven nur verwenden, um Geräteschnittstelleneigenschaften zu ändern, die für Windows Vista oder eine höhere Version von Windows-Betriebssystemen neu sind. Für Geräteschnittstelleneigenschaften, die unter Windows Server 2003, Windows XP oder Windows 2000 eingeführt wurden und entsprechende Registrierungswerteinträge aufweisen, sollten Sie weiterhin INF AddReg-Direktiven und INF DelReg-Anweisungen verwenden, um die Eigenschaften der Geräteschnittstelle festzulegen und zu löschen. Diese Richtlinien gelten für systemdefinierte Eigenschaften und benutzerdefinierte Eigenschaften. Weitere Informationen zur Verwendung der AddProperty-Direktive und der DelProperty-Anweisung finden Sie unter Verwenden der INF-AddProperty-Direktive und der INF DelProperty-Direktive.

In der Regel enthält ein add-interface-section nur eine INF AddReg-Direktive , die wiederum auf einen einzelnen add-registry-section verweist. Der Abschnitt add-registry-wird verwendet, um Informationen in der Registrierung zu den Schnittstellen zu speichern, die vom Gerätetreiber für die spätere Verwendung durch noch höhere Treiber und Anwendungen unterstützt werden.

Ein add-registry-section , auf den in einem add-interface-section verwiesen wird, ist spezifisch für die Instanzen für das Gerät, den Treiber und die Schnittstelle. Es kann über einen Werteintrag verfügen, der einen Anzeigenamen für die exportierte Geräteschnittstelle instance definiert, sodass noch höhere Komponenten mit ihrem Anzeigenamen in der Benutzeroberfläche auf diese Schnittstelle verweisen können.

Ein HKR , der in einem solchen Abschnitt "add-registry-section " angegeben wird, gibt den Laufzeitzugriffsstatusregistrierungsschlüssel für eine Geräteschnittstelle an. Der Treiber kann zur Laufzeit auf den in diesem Registrierungsschlüssel gespeicherten Zustand zugreifen, indem er IoOpenDeviceInterfaceRegistryKey aufruft , um einen HANDLE-Wert für den Statusregistrierungsschlüssel abzurufen. Benutzermoduskomponenten können den Zustand abfragen, indem sie CM_Open_Device_Interface_Key aufrufen.

Beispiele

Dieses Beispiel zeigt einen Teil der Erweiterung von DDInstall. Schnittstellenabschnitt für ein bestimmtes Audiogerät, das systemdefinierte Kernelstreamingschnittstellen unterstützt.

; ...
[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" 
; ...