Export (0) Print
Expand All

INF AddInterface Directive

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

Description

One or more AddInterface directives can be specified within an INF DDInstall.Interfaces section. This directive installs device-specific support for device interface classes exported to higher level components, such as other drivers or applications. The directive typically references an add-interface-section , which sets up registry information for the device-specific instance of the device interface class.

An exported device interface class can be one of the system-defined device interface classes, such as those that are defined by kernel streaming, or a new device interface class specified by an INF InterfaceInstall32 section.

Entries

InterfaceClassGUID

Specifies the GUID value that identifies the device interface class. This can be expressed as an explicit GUID value of the form {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn} or as a %strkey% token defined to "{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}" in a Strings section of the INF file.

For more information about how to create a GUID, see Using GUIDs in Drivers. For the system-defined interface class GUIDS, see the appropriate header, such as Ks.h for the kernel-streaming interface GUIDs.

reference-string

This optional value, associated with the device-specific instance of the specified interface class, can be expressed either as a "quoted string" or as a %strkey% token defined in an INF Strings section.

PnP function and filter drivers usually omit this value from the AddInterface= entries in their INF files. A reference-string is used by the swenum driver as a placeholder for software devices that are created on demand by using multiple instances of a single interface class. The same InterfaceClassGUID value can be specified in INF entries with two or more unique reference-strings. Because the I/O manager passes the reference-string value as a path component of the interface instance's name whenever it is opened, the installed driver can discriminate between interface instances of the same class for a single device.

add-interface-section

References the name of a section elsewhere in the INF file. This typically contains an INF AddReg directive to set up the registry entries exporting the driver's support of this device interface class. For more information, see the following Remarks section.

flags

If specified, this entry must be zero.

Remarks

If the device interface class identified by a specified {InterfaceClassGUID} is not installed already, the system setup code installs that class in the system. Any INF file that installs a new class also has an INF InterfaceInstall32 section. This section contains the specified {InterfaceClassGUID} and references an interface-install-section that sets up interface-specific installation operations for that class.

To enable an instance of a device interface class for run-time use by higher level components, the driver must make a call IoSetDeviceInterfaceState with each {InterfaceClassGUID} value identifying a device interface class that the driver supports on the underlying device. As an alternative to registering its support for a device interface class in its INF, a device driver can call IoRegisterDeviceInterface before it makes its initial call to IoSetDeviceInterfaceState. Usually, a PnP function or filter driver makes this call from its AddDevice routine.

Each AddInterface directive in an INF DDInstall.Interfaces section can reference an INF-writer-defined add-interface-section elsewhere in the INF file. Each INF-writer-defined section name must be unique within the INF file and must follow the general rules for defining section names. For more information about these rules, see General Syntax Rules for INF Files.

An add-interface-section referenced by the AddInterface directive has the following form:

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

Starting with Windows Vista, you can set device interface properties by including INF AddProperty directives in an add-interface section. You can also delete device interface properties by including INF DelProperty directives in an add-interface section. However, you should use AddProperty or DelProperty directives only to modify device interface properties that are new to Windows Vista or a later version of Windows operating systems. For device interface properties that were introduced on Windows Server 2003, Windows XP, or Windows 2000, and that have corresponding registry value entries, you should continue to use INF AddReg directives and INF DelReg directives to set and delete the device interface properties. These guidelines apply to system-defined properties and custom properties. For more information about how to use the AddProperty directive and DelProperty directive, see Using the INF AddProperty Directive and the INF DelProperty Directive.

Typically, an add-interface-section contains only an INF AddReg directive that, in turn, references a single add-registry-section. The add-registry-section is used to store information in the registry about the interfaces supported by the device driver for subsequent use by still higher level drivers and applications.

An add-registry-section referenced within an add-interface-section is specific to the instances for the device, driver, and interface. It might have a value entry defining a friendly name for the exported device interface instance so that still higher level components can refer to that interface by its friendly name in the user interface.

An HKR specified in such an add-registry-section section designates the user-mode-accessible device-interface subkey of the ..DeviceClasses\{InterfaceClassGUID}\ branch. In the registry, DeviceClasses is a subkey of the ..CurrentControlSet\Control key.

Examples

This example shows some of the expansion of the DDInstall.Interfaces section for a particular audio device that supports system-defined kernel-streaming interfaces.


; ...
[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_Topology%,\
ESSAud.Interface.Topology
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_CAPTURE%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_FMSynth%,WDM.Interface.FMSynth
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_FMSynth%,\
WDM.Interface.FMSynth

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

See also

AddProperty
AddReg
BitReg
CopyFiles
DDInstall.Interfaces
DelFiles
DelProperty
DelReg
Ini2Reg
InterfaceInstall32
IoRegisterDeviceInterface
IoSetDeviceInterfaceState
RenFiles
UpdateIniFields
UpdateInis

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft