Diretiva INF AddInterface

Artigo
06/15/2023

Uma ou mais diretivas AddInterface podem ser especificadas em uma seção INF DDInstall.Interfaces. Essa diretiva instala o suporte específico do dispositivo para classes de interface de dispositivo exportadas para componentes de nível superior, como outros drivers ou aplicativos. A diretiva normalmente faz referência a uma seção add-interface , que configura informações do Registro para a instância específica do dispositivo da classe de interface do dispositivo.

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

Uma classe de interface de dispositivo exportada pode ser uma das classes de interface de dispositivo definidas pelo sistema, como aquelas definidas pelo streaming de kernel ou uma nova classe de interface de dispositivo especificada por uma seção INF InterfaceInstall32.

Entradas

InterfaceClassGUID
Especifica o valor guid que identifica a classe de interface do dispositivo. Isso pode ser expresso como um valor GUID explícito do formulário {nnnnnnnn-nnnn-nnnn-nnnnnnnnnnnnnnnn-} ou como um token %strkey% definido como "{nnnnnnnn-nnnn-nnnn nnnn-nnnn-nnnnnnnnnnnn}" em uma seção Strings do arquivo INF.

Para obter mais informações sobre como criar um GUID, consulte Usando GUIDs em drivers. Para o GUIDS da classe de interface definida pelo sistema, consulte o cabeçalho apropriado, como Ks.h para os GUIDs da interface de streaming de kernel.

cadeia de caracteres de referência
Esse valor opcional, associado à instância específica do dispositivo da classe de interface especificada, pode ser expresso como uma "cadeia de caracteres entre aspas" ou como um token %strkey% definido em uma seção cadeias de caracteres INF.

A função PnP e os drivers de filtro geralmente omitem esse valor das entradas AddInterface= em seus arquivos INF. Uma cadeia de caracteres de referência é usada pelo driver swenum como um espaço reservado para dispositivos de software criados sob demanda usando várias instâncias de uma única classe de interface. O mesmo valor InterfaceClassGUID pode ser especificado em entradas INF com duas ou mais cadeias de caracteres de referênciaexclusivas. Como o gerenciador de E/S passa o valor de cadeia de caracteres de referência como um componente de caminho do nome da instância de interface sempre que ele é aberto, o driver instalado pode discriminar entre instâncias de interface da mesma classe para um único dispositivo.

add-interface-section
Faz referência ao nome de uma seção em outro lugar no arquivo INF. Normalmente, isso contém uma diretiva INF AddReg para configurar as entradas do Registro que exportam o suporte do driver dessa classe de interface do dispositivo. Para obter mais informações, consulte a seção Comentários a seguir.

sinalizadores
Se especificada, essa entrada deve ser zero.

Comentários

Se a classe de interface do dispositivo identificada por um {InterfaceClassGUID} especificado ainda não estiver instalada, o código de instalação do sistema instalará essa classe no sistema. Qualquer arquivo INF que instale uma nova classe também pode ter uma seção INTERFACEInstall32 do INF. Esta seção contém o {InterfaceClassGUID} especificado e faz referência a uma interface-install-section que configura operações de instalação específicas da interface para essa classe.

Para habilitar uma instância de uma classe de interface de dispositivo para uso em tempo de execução por componentes de nível superior, um driver de dispositivo deve primeiro chamar IoRegisterDeviceInterface para recuperar o nome simbólico do link da instância de interface do dispositivo para habilitar. Normalmente, uma função PnP ou um driver de filtro faz essa chamada de sua rotina AddDevice . Para habilitar instâncias de interfaces de dispositivo provisionadas no INF, o driver de dispositivo deve fornecer {InterfaceClassGUID} e a cadeia de caracteres de referência especificadas no INF quando chama IoRegisterDeviceInterface. Em seguida, o driver chama IoSetDeviceInterfaceState para habilitar a interface usando o nome de link simbólico retornado por IoRegisterDeviceInterface.

Cada diretiva AddInterface em uma seção INF DDInstall.Interfaces pode referenciar uma seção add-interface definida pelo gravador INF em outro lugar no arquivo INF. Cada nome de seção definido pelo gravador INF deve ser exclusivo dentro do arquivo INF e deve seguir as regras gerais para definir nomes de seção. Para obter mais informações sobre essas regras, consulte Regras de sintaxe geral para arquivos INF.

Uma seção add-interface referenciada pela diretiva AddInterface tem o seguinte formato:

[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 partir do Windows Vista, você pode definir as propriedades da interface do dispositivo incluindo as diretivas ADDProperty do INF em uma seção de interface de adição. Você também pode excluir propriedades da interface do dispositivo incluindo diretivas INF DelProperty em uma seção de interface de adição. No entanto, você deve usar as diretivas AddProperty ou DelProperty apenas para modificar as propriedades da interface do dispositivo que são novas no Windows Vista ou em uma versão posterior dos sistemas operacionais Windows. Para propriedades de interface do dispositivo que foram introduzidas no Windows Server 2003, Windows XP ou Windows 2000 e que têm entradas de valor de registro correspondentes, você deve continuar a usar diretivas INF AddReg e diretivas INF DelReg para definir e excluir as propriedades da interface do dispositivo. Essas diretrizes se aplicam a propriedades definidas pelo sistema e propriedades personalizadas. Para obter mais informações sobre como usar a diretiva AddProperty e a diretiva DelProperty , consulte Using the INF AddProperty Directive and the INF DelProperty Directive.

Normalmente, uma add-interface-section contém apenas uma diretiva InF AddReg que, por sua vez, faz referência a uma única seção add-registry. A seção add-registry é usada para armazenar informações no registro sobre as interfaces compatíveis com o driver de dispositivo para uso subsequente por drivers e aplicativos de nível ainda mais alto.

Uma seção add-registry referenciada em uma seção add-interface é específica para as instâncias do dispositivo, driver e interface. Ele pode ter uma entrada de valor definindo um nome amigável para a instância de interface do dispositivo exportada para que os componentes de nível ainda mais alto possam se referir a essa interface pelo nome amigável na interface do usuário.

Um HKR especificado em tal seção add-registry-section designa a chave do Registro de estado acessível em tempo de execução para uma interface do dispositivo. O driver pode acessar o estado armazenado nessa chave do Registro em runtime chamando IoOpenDeviceInterfaceRegistryKey para recuperar um HANDLE para a chave do Registro de estado. Os componentes do modo de usuário podem consultar o estado chamando CM_Open_Device_Interface_Key.

Exemplos

Este exemplo mostra parte da expansão do DDInstall. Seção interfaces para um dispositivo de áudio específico que dá suporte a interfaces de streaming de kernel definidas pelo 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" 
; ...