Usando interfaces de dispositivo em drivers UMDF

  • Artigo

Aviso

O UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2.

Os exemplos de UMDF 1 arquivados podem ser encontrados no Windows 11, versão 22H2 – Atualização de exemplos de driver de maio de 2022.

Para obter mais informações, consulte Introdução com UMDF.

Uma interface do dispositivo é um link simbólico para um dispositivo PnP (Plug and Play) que um aplicativo pode usar para acessar o dispositivo. Um aplicativo no modo de usuário pode passar o nome simbólico do link da interface para um elemento de API, como a função CreateFile do Microsoft Win32. Para obter o nome simbólico do link de uma interface do dispositivo, o aplicativo de modo de usuário pode chamar funções SetupDi . Para obter mais informações sobre as funções SetupDi, consulte SetupDi Device Interface Functions.

Cada interface do dispositivo pertence a uma classe de interface do dispositivo. Por exemplo, uma pilha de driver para um dispositivo CD-ROM pode fornecer uma interface que pertence à classe GUID_DEVINTERFACE_CDROM. Um dos drivers do dispositivo CD-ROM registraria uma instância da classe GUID_DEVINTERFACE_CDROM para informar ao sistema e aos aplicativos que um dispositivo CD-ROM está disponível. Para obter mais informações sobre classes de interface do dispositivo, consulte Introdução às interfaces de dispositivo.

Registrando uma interface do dispositivo

Para registrar uma instância de uma classe de interface de dispositivo, um driver baseado em UMDF pode chamar IWDFDevice::CreateDeviceInterface de dentro de sua função de retorno de chamada IDriverEntry::OnDeviceAdd . Se o driver der suporte a várias instâncias da interface, ele poderá atribuir uma cadeia de caracteres de referência exclusiva a cada instância.

Habilitar e desabilitar uma interface do dispositivo

Se a criação for bem-sucedida, a estrutura habilitará e desabilita automaticamente a interface com base no estado PnP do dispositivo.

Além disso, um driver pode desabilitar e reabilitar uma interface do dispositivo conforme necessário. Por exemplo, se um driver determinar que seu dispositivo parou de responder, o driver poderá chamar IWDFDevice::AssignDeviceInterfaceState para desabilitar as interfaces do dispositivo e proibir os aplicativos de obter novos identificadores para a interface. (Os identificadores existentes para a interface não são afetados.) Se o dispositivo posteriormente ficar disponível, o driver poderá chamar IWDFDevice::AssignDeviceInterfaceState novamente para reabilitar as interfaces.

Recebendo solicitações para acessar uma interface do dispositivo

Quando um aplicativo solicita acesso à interface do dispositivo de um driver, a estrutura chama a função de retorno de chamada IQueueCallbackCreate::OnCreateFile do driver. O driver pode chamar IWDFFile::RetrieveFileName para obter o nome do dispositivo ou arquivo que o aplicativo está acessando. Se o driver tiver especificado uma cadeia de caracteres de referência quando registrou a interface do dispositivo, o sistema operacional incluirá a cadeia de caracteres de referência no nome do arquivo ou dispositivo que IWDFFile::RetrieveFileName retorna.

Criando eventos de dispositivo

O driver baseado em UMDF pode criar eventos personalizados específicos do dispositivo (chamados de eventos de dispositivo) chamando IWDFDevice::P ostEvent. Um driver registrado para usar qualquer uma das interfaces do dispositivo pode receber notificações de eventos personalizados de um dispositivo. Os drivers baseados em UMDF recebem essas notificações fornecendo uma função de retorno de chamada IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent .

Eventos personalizados são exclusivos para o dispositivo. Tanto o desenvolvedor do driver que cria o evento quanto o desenvolvedor do driver que recebe o evento devem entender o significado do evento.

Acessando a interface do dispositivo de outro driver

Se você quiser que o driver baseado em UMDF envie solicitações de E/S para uma interface de dispositivo fornecida por outro driver, você poderá criar um destino de E/S remoto que represente a interface do dispositivo.

Primeiro, o driver deve se registrar para receber uma notificação quando uma interface do dispositivo estiver disponível. Use as seguintes etapas:

  1. Quando o driver chama IWDFDriver::CreateDevice, o driver pode fornecer uma interface IPnpCallbackRemoteInterfaceNotification . A função de retorno de chamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival dessa interface informa ao driver quando as interfaces do dispositivo estão disponíveis.

  2. Depois que o driver chamar IWDFDriver::CreateDevice, ele poderá chamar IWDFDevice2::RegisterRemoteInterfaceNotification para cada interface de dispositivo que o driver usará.

Posteriormente, a estrutura chama a função de retorno de chamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival do driver sempre que uma interface de dispositivo especificada estiver disponível. A função de retorno de chamada pode chamar IWDFRemoteInterfaceInitialize::GetInterfaceGuid e IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink para determinar qual interface do dispositivo chegou.

A função de retorno de chamada IPnpCallbackRemoteInterfaceNotification do driver::OnRemoteInterfaceArrival normalmente deve fazer o seguinte:

  1. Chame IWDFDevice2::CreateRemoteInterface para criar um objeto de interface remota, opcionalmente fornecendo interfaces IRemoteInterfaceCallbackEvent e IRemoteInterfaceCallbackRemoval .

  2. Chame IWDFDevice2::CreateRemoteTarget para criar um objeto de destino remoto, opcionalmente fornecendo uma interface IRemoteTargetCallbackRemoval .

  3. Chame IWDFRemoteTarget::OpenRemoteInterface para conectar a interface do dispositivo ao destino remoto.

    Se a interface do dispositivo for aquela que o enumerador de dispositivo de software SWENUM cria, seu driver deverá chamar OpenRemoteInterface de um item de trabalho. (Por exemplo, consulte a função QueueUserWorkItem no SDK do Windows.)

Agora, o driver pode formatar e enviar solicitações de E/S para o destino de E/S remoto.

Além da função de retorno de chamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival , um driver baseado em UMDF pode fornecer duas funções de retorno de chamada adicionais para receber notificações de eventos de interface do dispositivo: