Directive INF AddInterface

Article
06/15/2023

Une ou plusieurs directives AddInterface peuvent être spécifiées dans une section INF DDInstall.Interfaces. Cette directive installe la prise en charge spécifique aux appareils pour les classes d’interface de périphérique exportées vers des composants de niveau supérieur, tels que d’autres pilotes ou applications. La directive fait généralement référence à une section add-interface , qui configure les informations de Registre pour les instance spécifiques à l’appareil de la classe d’interface d’appareil.

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

Une classe d’interface d’appareil exportée peut être l’une des classes d’interface d’appareil définies par le système, telles que celles qui sont définies par la diffusion en continu du noyau, ou une nouvelle classe d’interface d’appareil spécifiée par une section Inf InterfaceInstall32.

Entrées

InterfaceClassGUID
Spécifie la valeur GUID qui identifie la classe d’interface d’appareil. Cette valeur peut être exprimée sous la forme d’une valeur GUID explicite de la forme {nnnnnn-nnnn--nnnnnn-} ou sous la forme d’un jeton %strkey% défini sur « {nnnnnn-nnnn-nnnn-nnnn nnnnnn-} » dans une section Strings du fichier INF.

Pour plus d’informations sur la création d’un GUID, consultez Utilisation de GUID dans les pilotes. Pour les GUID de la classe d’interface définie par le système, consultez l’en-tête approprié, tel que Ks.h pour les GUID d’interface de diffusion en continu du noyau.

reference-string
Cette valeur facultative, associée à l’instance spécifique à l’appareil de la classe d’interface spécifiée, peut être exprimée sous la forme d’une «chaîne entre guillemets» ou d’un jeton %strkey% défini dans une section Inf Strings.

Les pilotes de fonction et de filtre PnP omettent généralement cette valeur des entrées AddInterface= dans leurs fichiers INF. Une chaîne de référence est utilisée par le pilote swenum comme espace réservé pour les périphériques logiciels créés à la demande à l’aide de plusieurs instances d’une seule classe d’interface. La même valeur InterfaceClassGUID peut être spécifiée dans les entrées INF avec au moins deux chaînes de référenceuniques. Étant donné que le gestionnaire d’E/S transmet la valeur de chaîne de référence en tant que composant de chemin du nom de l’interface instance chaque fois qu’il est ouvert, le pilote installé peut faire la distinction entre les instances d’interface de la même classe pour un seul appareil.

add-interface-section
Fait référence au nom d’une section ailleurs dans le fichier INF. Il contient généralement une directive AddReg INF pour configurer les entrées de Registre qui exportent la prise en charge par le pilote de cette classe d’interface de périphérique. Pour plus d’informations, consultez la section Notes suivante.

flags
Si elle est spécifiée, cette entrée doit être égale à zéro.

Remarques

Si la classe d’interface d’appareil identifiée par un {InterfaceClassGUID} spécifié n’est pas déjà installée, le code de configuration du système installe cette classe dans le système. Tout fichier INF qui installe une nouvelle classe peut également avoir une section Inf InterfaceInstall32. Cette section contient le {InterfaceClassGUID} spécifié et fait référence à une section d’installation d’interface qui configure des opérations d’installation spécifiques à l’interface pour cette classe.

Pour activer une instance d’une classe d’interface d’appareil pour une utilisation au moment de l’exécution par des composants de niveau supérieur, un pilote de périphérique doit d’abord appeler IoRegisterDeviceInterface pour récupérer le nom de lien symbolique de l’interface de périphérique instance à activer. En règle générale, une fonction PnP ou un pilote de filtre effectue cet appel à partir de sa routine AddDevice . Pour activer les instances d’interfaces d’appareil approvisionnées dans l’INF, le pilote de périphérique doit fournir la {InterfaceClassGUID} et la chaîne de référence spécifiées dans l’inf lorsqu’il appelle IoRegisterDeviceInterface. Le pilote appelle ensuite IoSetDeviceInterfaceState pour activer l’interface à l’aide du nom de lien symbolique retourné par IoRegisterDeviceInterface.

Chaque directive AddInterface d’une section INF DDInstall.Interfaces peut faire référence à une section add-interface définie par un writer INF ailleurs dans le fichier INF. Chaque nom de section défini par l’enregistreur INF doit être unique dans le fichier INF et doit suivre les règles générales de définition des noms de section. Pour plus d’informations sur ces règles, consultez Règles de syntaxe générales pour les fichiers INF.

Une section add-interface référencée par la directive AddInterface se présente sous la forme suivante :

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

À compter de Windows Vista, vous pouvez définir les propriétés de l’interface d’appareil en incluant des directives Inf AddProperty dans une section d’interface complémentaire. Vous pouvez également supprimer des propriétés d’interface d’appareil en incluant des directives INF DelProperty dans une section d’interface complémentaire. Toutefois, vous devez utiliser les directives AddProperty ou DelProperty uniquement pour modifier les propriétés de l’interface d’appareil qui sont nouvelles pour Windows Vista ou une version ultérieure des systèmes d’exploitation Windows. Pour les propriétés d’interface d’appareil introduites sur Windows Server 2003, Windows XP ou Windows 2000 et qui ont des entrées de valeur de Registre correspondantes, vous devez continuer à utiliser les directives INF AddReg et INF DelReg pour définir et supprimer les propriétés de l’interface de l’appareil. Ces instructions s’appliquent aux propriétés définies par le système et aux propriétés personnalisées. Pour plus d’informations sur l’utilisation de la directive AddProperty et de la directive DelProperty , consultez Using the INF AddProperty Directive and the INF DelProperty Directive.

En règle générale, une section add-interface contient uniquement une directive Inf AddReg qui, à son tour, fait référence à une section add-registry-section unique. La section add-registry est utilisée pour stocker dans le registre des informations sur les interfaces prises en charge par le pilote de périphérique en vue d’une utilisation ultérieure par des pilotes et des applications de niveau supérieur.

Une section add-registry référencée dans une section add-interface est spécifique aux instances du périphérique, du pilote et de l’interface. Il peut avoir une entrée de valeur définissant un nom convivial pour l’interface de l’appareil exporté instance afin que les composants de niveau supérieur puissent faire référence à cette interface par son nom convivial dans l’interface utilisateur.

Un HKR spécifié dans une section de ce type add-registry-section désigne la clé de Registre d’état accessible à l’exécution pour une interface d’appareil. Le pilote peut accéder à l’état stocké dans cette clé de Registre au moment de l’exécution en appelant IoOpenDeviceInterfaceRegistryKey pour récupérer un HANDLE dans la clé de Registre d’état. Les composants du mode utilisateur peuvent interroger l’état en appelant CM_Open_Device_Interface_Key.

Exemples

Cet exemple montre une partie de l’expansion de DDInstall. Section Interfaces pour un périphérique audio particulier qui prend en charge les interfaces de diffusion en continu de noyau définies par le système.

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