Usando objetos de dispositivo de controle

Um objeto de dispositivo de controle é um objeto de dispositivo de estrutura que não dá suporte a Plug and Play (PnP) ou operações de gerenciamento de energia. Os drivers podem usar objetos de dispositivo de controle para representar dispositivos virtuais somente software ou dispositivos de hardware herdados (ou seja, dispositivos que não fornecem recursos de gerenciamento de energia ou PnP).

Um driver que cria um objeto de dispositivo de controle também normalmente cria um link simbólico para o objeto do dispositivo. Os aplicativos podem enviar solicitações de E/S para o objeto do dispositivo de controle passando o nome simbólico do link para um elemento de API, como a função CreateFile do Microsoft Win32.

A estrutura não anexa objetos de dispositivo de controle a uma pilha de dispositivos. Portanto, quando um aplicativo envia uma solicitação de E/S para um objeto de dispositivo de controle, o gerenciador de E/S entrega a solicitação diretamente ao driver que criou o objeto do dispositivo de controle, em vez de para o driver na parte superior da pilha. (No entanto, um driver adicional pode chamar IoAttachDevice para anexar um objeto de dispositivo acima do objeto do dispositivo de controle. Nesse caso, o driver adicional recebe a solicitação de E/S primeiro.)

Usos de objetos de dispositivo de controle

Dois usos típicos para dispositivos de controle são:

1. Um driver de filtro para um dispositivo PnP, se o driver der suporte a um conjunto de códigos de controle de E/S personalizados para os aplicativos usarem.

   Se um aplicativo tentou enviar os códigos de controle de E/S personalizados para a parte superior da pilha do driver (usando, por exemplo, o nome simbólico do link de uma interface do dispositivo), um driver acima do driver de filtro poderá falhar na solicitação de E/S se o driver não reconhecesse os códigos de controle de E/S personalizados. Para evitar esse problema, o driver de filtro pode criar um objeto de dispositivo de controle. Os aplicativos podem usar o nome de link simbólico do objeto de dispositivo de controle para enviar códigos de controle de E/S diretamente para o driver de filtro.

   (Observe que uma maneira melhor para o driver de filtro evitar o problema é agir como um motorista de ônibus e enumerar dispositivos filho que operam no modo bruto. Em outras palavras, para cada dispositivo compatível com o driver de filtro, o driver pode criar um PDO (objeto de dispositivo físico) que não requer um driver de função. O driver chama WdfPdoInitAssignRawDevice e WdfDeviceInitAssignName para cada um desses dispositivos, e o aplicativo pode identificar um dispositivo pelo nome ao enviar um código de controle de E/S personalizado.)

2. Um driver para um dispositivo que não dá suporte a PnP.

   Esse driver deve usar objetos de dispositivo de controle, pois os objetos de dispositivo para esses dispositivos não residem em uma pilha de dispositivos e não fornecem recursos PnP. Para obter mais informações sobre como dar suporte a dispositivos não PnP, consulte Using Kernel-Mode Driver Framework with Non-PnP Drivers.

Criando um objeto de dispositivo de controle

Para criar um objeto de dispositivo de controle, um driver deve:

1. Chame WdfControlDeviceInitAllocate para obter uma estrutura WDFDEVICE_INIT .

2. Chame métodos de inicialização de objeto, conforme necessário, para inicializar a estrutura WDFDEVICE_INIT. O driver pode chamar apenas os seguintes métodos de inicialização:

   • WdfControlDeviceInitSetShutdownNotification
   • WdfDeviceInitAssignName
   • WdfDeviceInitAssignSDDLString
   • WdfDeviceInitAssignWdmIrpPreprocessCallback
   • WdfDeviceInitSetCharacteristics
   • WdfDeviceInitSetDeviceClass
   • WdfDeviceInitSetExclusive
   • WdfDeviceInitSetFileObjectConfig
   • WdfDeviceInitSetIoInCallerContextCallback
   • WdfDeviceInitSetIoType
   • WdfDeviceInitSetRequestAttributes

3. Chame WdfDeviceCreate, que usa o conteúdo da estrutura WDFDEVICE_INIT para criar um objeto de dispositivo de estrutura.

4. Conclua as seguintes operações de inicialização:

   • Crie uma fila de E/S padrão para o dispositivo, se necessário.
   • Chame WdfDeviceConfigureRequestDispatching, se necessário.
   • Chame WdfDeviceCreateSymbolicLink para criar um nome de link simbólico que os aplicativos podem usar para acessar o dispositivo de controle.

5. Chame WdfControlFinishInitializing.

Regras para usar objetos de dispositivo de controle

Os drivers que criam objetos de dispositivo de controle devem obedecer às seguintes regras:

• Os drivers não podem passar o identificador do objeto do dispositivo de controle para métodos de estrutura que enumeram dispositivos filho.

• Os drivers não podem passar o identificador do objeto do dispositivo de controle para métodos de estrutura que dão suporte a interfaces de dispositivo.

• Os drivers podem criar filas de E/S e registrar manipuladores de solicitação para as filas, mas a estrutura não permite que as filas sejam gerenciadas por energia.

• Os drivers podem criar objetos de arquivo para objetos de dispositivo de controle.

Nomeando um objeto de dispositivo de controle

Todos os objetos de dispositivo de controle devem ser nomeados. Normalmente, seu driver chamará WdfDeviceInitAssignName para atribuir um nome de dispositivo e, em seguida, chamará WdfDeviceCreateSymbolicLink para criar um nome de link simbólico que os aplicativos podem usar para acessar o objeto.

Se o driver não chamar WdfDeviceInitAssignName para atribuir um nome de dispositivo, a estrutura gerará automaticamente um nome para dispositivos de controle, mas seu driver não poderá chamar WdfDeviceCreateSymbolicLink.

Seu driver pode chamar WdfDeviceInitSetDeviceClass para especificar uma classe de configuração de dispositivo para um dispositivo de controle. A classe de configuração do dispositivo identifica uma seção do registro que contém informações fornecidas pelo administrador sobre dispositivos que pertencem à classe de instalação. Para obter mais informações sobre como chamar WdfDeviceInitSetDeviceClass, consulte Controling Device Access in Framework-Based Drivers.

Recebendo notificação de desligamento do sistema

Como os objetos do dispositivo de controle não dão suporte a PnP, o driver não pode registrar funções de retorno de chamada que informam o driver quando o estado de energia de um dispositivo é alterado. No entanto, o driver pode chamar WdfControlDeviceInitSetShutdownNotification para registrar uma função de retorno de chamada EvtDeviceShutdownNotification . Essa função de retorno de chamada informa o driver quando o sistema está prestes a perder a potência.

Excluindo um objeto de dispositivo de controle

Alguns drivers precisam excluir seus objetos de dispositivo de controle antes que o driver descarregue, da seguinte maneira:

• Se o driver criar objetos de dispositivo de controle (que não dão suporte a PnP ou gerenciamento de energia) e se o driver também criar objetos de dispositivo de estrutura que dão suporte a PnP e gerenciamento de energia, o driver deverá eventualmente chamar WdfObjectDelete em IRQL = PASSIVE_LEVEL para excluir os objetos do dispositivo de controle.

  Se o driver criar ambos os tipos de objetos de dispositivo, o sistema operacional não poderá descarregar seu driver até que o driver tenha excluído os objetos do dispositivo de controle.

  No entanto, o driver não deve excluir os objetos do dispositivo de controle até que a estrutura tenha excluído os outros objetos do dispositivo. Para determinar quando a estrutura excluiu os outros objetos de dispositivo, o driver deve fornecer funções EvtCleanupCallback para esses objetos.

• Se o driver criar objetos de dispositivo de controle, mas não criar objetos de dispositivo de estrutura que dão suporte ao PnP e ao gerenciamento de energia, o driver não precisará excluir os objetos do dispositivo de controle.

  Nesse caso, a estrutura exclui os objetos do dispositivo de controle após o retorno da função de retorno de chamada EvtDriverUnload do driver.