Direttiva INF AddInterface

Articolo
02/02/2024

È possibile specificare una o più direttive AddInterface all'interno di una sezione INF DDInstall.Interfaces. Questa direttiva installa il supporto specifico del dispositivo per le classi di interfaccia del dispositivo esportate in componenti di livello superiore, ad esempio altri driver o applicazioni. La direttiva fa in genere riferimento a una sezione add-interface-che configura le informazioni del Registro di sistema per l'istanza specifica del dispositivo della classe dell'interfaccia del dispositivo.

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

Una classe di interfaccia dispositivo esportata può essere una delle classi di interfaccia del dispositivo definite dal sistema, ad esempio quelle definite dal flusso del kernel o una nuova classe di interfaccia del dispositivo specificata da una sezione INF InterfaceInstall32.

Voci

InterfaceClassGUID
Specifica il valore GUID che identifica la classe dell'interfaccia del dispositivo. Può essere espresso come valoreGUID esplicito del formato {nnnn-nnnn-nnnn--}o come token %strkey% definito in "{-nnnn---}" in una sezione Strings del file INF.

Per altre informazioni su come creare un GUID, vedere Uso dei GUID nei driver. Per il GUIDS della classe di interfaccia definita dal sistema, vedere l'intestazione appropriata, ad esempio Ks.h per i GUID dell'interfaccia di streaming kernel.

reference-string
Questo valore facoltativo, associato all'istanza specifica del dispositivo della classe di interfaccia specificata, può essere espresso come "stringa tra virgolette" o come token %strkey% definito in una sezione Stringhe INF.

I driver di funzione e filtro PnP omettono in genere questo valore dalle voci AddInterface= nei file INF. Una stringa di riferimento viene usata dal driver swenum come segnaposto per i dispositivi software creati su richiesta usando più istanze di una singola classe di interfaccia. Lo stesso valore InterfaceClassGUID può essere specificato nelle voci INF con due o più stringhe di riferimento univoche. Poiché il gestore di I/O passa il valore della stringa di riferimento come componente del percorso del nome dell'istanza di interfaccia ogni volta che viene aperto, il driver installato può distinguere tra istanze di interfaccia della stessa classe per un singolo dispositivo.

add-interface-section
Fa riferimento al nome di una sezione altrove nel file INF. Contiene in genere una direttiva INF AddReg per configurare le voci del Registro di sistema che esportano il supporto del driver di questa classe dell'interfaccia del dispositivo. Per altre informazioni, vedere la sezione Osservazioni seguente.

flags
Se specificato, questa voce deve essere zero.

Commenti

Se la classe dell'interfaccia del dispositivo identificata da un oggetto {InterfaceClassGUID} specificato non è già installata, il codice di installazione del sistema installa tale classe nel sistema. Qualsiasi file INF che installa una nuova classe può avere anche una sezione INF InterfaceInstall32. Questa sezione contiene l'oggetto {InterfaceClassGUID} specificato e fa riferimento a una sezione interface-install-section che configura le operazioni di installazione specifiche dell'interfaccia per tale classe.

Per abilitare un'istanza di una classe di interfaccia dispositivo per l'uso in fase di esecuzione da parte di componenti di livello superiore, un driver di dispositivo deve prima chiamare IoRegisterDeviceInterface per recuperare il nome di collegamento simbolico dell'istanza dell'interfaccia del dispositivo da abilitare. In genere, una funzione PnP o un driver di filtro effettua questa chiamata dalla routine AddDevice . Per abilitare le istanze delle interfacce di dispositivo di cui è stato effettuato il provisioning in INF, il driver di dispositivo deve specificare {InterfaceClassGUID} e la stringa di riferimento specificata in INF quando chiama IoRegisterDeviceInterface. Il driver chiama quindi IoSetDeviceInterfaceState per abilitare l'interfaccia usando il nome del collegamento simbolico restituito da IoRegisterDeviceInterface.

Ogni direttiva AddInterface in una sezione INF DDInstall.Interfaces può fare riferimento a una sezione add-interface-defined inF-writer altrove nel file INF. Ogni nome di sezione definito dal writer INF deve essere univoco all'interno del file INF e deve seguire le regole generali per la definizione dei nomi di sezione. Per altre informazioni su queste regole, vedere Regole di sintassi generali per i file INF.

Una sezione add-interface a cui fa riferimento la direttiva AddInterface ha il formato seguente:

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

A partire da Windows Vista, è possibile impostare le proprietà dell'interfaccia del dispositivo includendo le direttive INF AddProperty in una sezione add-interface. È anche possibile eliminare le proprietà dell'interfaccia del dispositivo includendo le direttive INF DelProperty in una sezione add-interface. È tuttavia consigliabile usare le direttive AddProperty o DelProperty solo per modificare le proprietà dell'interfaccia del dispositivo nuove in Windows Vista o in una versione successiva dei sistemi operativi Windows. Per le proprietà dell'interfaccia del dispositivo introdotte in Windows Server 2003, Windows XP o Windows 2000 e che hanno voci di valore del Registro di sistema corrispondenti, è consigliabile continuare a usare le direttive INF AddReg e le direttive INF DelReg per impostare ed eliminare le proprietà dell'interfaccia del dispositivo. Queste linee guida si applicano alle proprietà definite dal sistema e alle proprietà personalizzate. Per altre informazioni su come usare la direttiva AddProperty e la direttiva DelProperty , vedere Using the INF AddProperty Directive and the INF DelProperty Directive.

In genere, una sezione add-interface-contiene solo una direttiva INF AddReg che, a sua volta, fa riferimento a una singola sezione del Registro di sistema del componente aggiuntivo. La sezione add-registry viene usata per archiviare informazioni nel Registro di sistema sulle interfacce supportate dal driver di dispositivo per un uso successivo da parte di driver e applicazioni di livello superiore.

Una sezione add-registry a cui si fa riferimento all'interno di una sezione add-interface-è specifica per le istanze per il dispositivo, il driver e l'interfaccia. Potrebbe avere una voce di valore che definisce un nome descrittivo per l'istanza dell'interfaccia del dispositivo esportata in modo che i componenti di livello più elevato possano fare riferimento a tale interfaccia in base al nome descrittivo nell'interfaccia utente.

Un HKR specificato in tale sezione add-registry-section definisce la chiave del Registro di sistema accessibile in fase di esecuzione per un'interfaccia del dispositivo. Il driver può accedere allo stato archiviato in questa chiave del Registro di sistema in fase di esecuzione chiamando IoOpenDeviceInterfaceRegistryKey per recuperare un HANDLE nella chiave del Registro di sistema di stato. I componenti in modalità utente possono eseguire query sullo stato chiamando CM_Open_Device_Interface_Key.

Esempio

In questo esempio viene illustrata un'espansione di DDInstall. Sezione Interfacce per un particolare dispositivo audio che supporta interfacce di streaming kernel definite dal sistema.

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