Usando Interfaces de Dispositivo (WDF)

Uma interface de dispositivo é uma ligação simbólica para um dispositivo Plug and Play (PnP) que uma aplicação pode usar para aceder ao dispositivo. Um aplicativo de modo de usuário pode passar o nome de link simbólico da interface para um elemento de API, como a função de Microsoft Win32 CreateFile. Para obter o nome simbólico de uma interface de dispositivo, a aplicação em modo de utilizador pode chamar as funções do gerenciador de configuração ou as funções SetupApi . Para obter mais informações, consulte enumerando interfaces de dispositivo instaladas.

Cada interface de dispositivo pertence a uma classe de interface de dispositivo . Por exemplo, uma pilha de drivers 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 o sistema e os aplicativos de que um dispositivo CD-ROM está disponível. Para obter mais informações sobre classes de interface de dispositivo, consulte Visão geral de classes de interface de dispositivo.

Registrando uma interface de dispositivo

Para registrar uma instância de uma classe de interface de dispositivo, um driver baseado em estrutura pode chamar WdfDeviceCreateDeviceInterface antes ou depois do dispositivo ser iniciado. Se o driver oferecer suporte a várias instâncias da interface, ele poderá atribuir uma cadeia de caracteres de referência exclusiva a cada instância.

Depois que o driver tiver registrado uma interface de dispositivo, o driver pode chamar WdfDeviceRetrieveDeviceInterfaceString para obter o nome de link simbólico que o sistema atribuiu à interface do dispositivo.

Para obter informações sobre outras maneiras pelas quais os drivers podem registrar interfaces de dispositivo, consulte Registrando uma classe de interface de dispositivo.

Ativando e desativando uma interface de dispositivo

As interfaces criadas antes do dispositivo iniciar (por exemplo, a partir de EvtDriverDeviceAdd, EvtChildListCreateDeviceou EvtDevicePrepareHardware) são ativadas automaticamente pela estrutura quando o dispositivo passa pela enumeração PnP e é iniciado. Para evitar que a interface seja ativada automaticamente durante o início do PnP, chame WdfDeviceSetDeviceInterfaceStateEx da mesma função de retorno de chamada (defina o parâmetro EnableInterface como FALSE) para essa interface antes do início do PnP.

As interfaces criadas depois que o dispositivo já é iniciado não serão ativadas automaticamente. O driver deve chamar WdfDeviceSetDeviceInterfaceState ou WdfDeviceSetDeviceInterfaceStateEx para habilitar essas interfaces.

Todas as interfaces são automaticamente desativadas quando o dispositivo sofre remoção PnP. Observe que qualquer alteração no estado de energia do dispositivo ou reequilíbrio de recursos PnP não altera o estado da interface.

Um driver pode desativar e reativar uma interface de dispositivo, se necessário. Por exemplo, se um driver determinar que seu dispositivo parou de responder, o driver pode chamar WdfDeviceSetDeviceInterfaceState ou WdfDeviceSetDeviceInterfaceStateEx para desativar as interfaces do dispositivo e proibir aplicativos de obter novos identificadores para a interface. (As alças existentes na interface não são afetadas.) Se o dispositivo mais tarde ficar disponível, o driver pode chamar WdfDeviceSetDeviceInterfaceState ou WdfDeviceSetDeviceInterfaceStateEx novamente para reativar as interfaces.

Recebendo solicitações para acessar uma interface de dispositivo

Quando um aplicativo ou componente em modo kernel solicita acesso à interface de dispositivo de um driver, o framework chama a função de retorno de chamada EvtDeviceFileCreate do driver. O driver pode chamar WdfFileObjectGetFileName para obter o nome do dispositivo ou arquivo que o aplicativo ou componente de modo kernel está acessando. Se o driver especificou uma cadeia de caracteres de referência quando registrou a interface do dispositivo, o sistema operacional inclui a cadeia de referência no arquivo ou nome do dispositivo que WdfFileObjectGetFileName retorna.

Aceder à interface do dispositivo de outro controlador

Esta seção mostra como um driver do Driver Framework Kernel-Mode (KMDF) ou um driver do Driver Framework User-Mode (UMDF) versão 2 se registra para receber notificações de chegada ou remoção de uma interface de dispositivo fornecida por outro driver e, em seguida, cria um alvo de I/O remoto para se comunicar com o dispositivo representado pela interface do dispositivo.

Para obter informações sobre como fazer isso em um driver UMDF versão 1, consulte Usando interfaces de dispositivo em drivers UMDF.

Para se registrar para notificação de eventos da interface do dispositivo, um driver KMDF chama IoRegisterPlugPlayNotification, enquanto um driver UMDF 2 chama CM_Register_Notification. Em ambos os casos, o driver chama a rotina apropriada a partir da sua função de retorno de chamada EvtDriverDeviceAdd.

O exemplo de código a seguir mostra como um driver UMDF 2 local se registra para notificações e, em seguida, abre o destino de E/S remoto.

O driver remoto regista uma interface de dispositivo chamando WdfDeviceCreateDeviceInterface a partir de EvtDriverDeviceAdd.

    UNICODE_STRING ref;
    RtlInitUnicodeString(&ref, MY_HID_FILTER_REFERENCE_STRING);
    status = WdfDeviceCreateDeviceInterface(
                 hDevice,
                 (LPGUID) &GUID_DEVINTERFACE_MY_HIDFILTER_DRIVER,
                 &ref // ReferenceString
             );

    if (!NT_SUCCESS (status)) {
        MyKdPrint( ("WdfDeviceCreateDeviceInterface failed 0x%x\n", status));
        return status;
    }

O driver local chama CM_Register_Notification de EvtDriverDeviceAdd para se registrar para notificação quando uma interface de dispositivo estiver disponível. Forneça um ponteiro para uma rotina de retorno de chamada de notificação que o framework chama quando as interfaces do dispositivo estiverem disponíveis.

DWORD cmRet;
    CM_NOTIFY_FILTER cmFilter;

    ZeroMemory(&cmFilter, sizeof(cmFilter));
    cmFilter.cbSize = sizeof(cmFilter);
    cmFilter.FilterType = CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE;
    cmFilter.u.DeviceInterface.ClassGuid = GUID_DEVINTERFACE_MY_HIDFILTER_DRIVER;

    cmRet = CM_Register_Notification(
                &cmFilter,                     // PCM_NOTIFY_FILTER pFilter,
                (PVOID) hDevice,               // PVOID pContext,
                MyCmInterfaceNotification,    // PCM_NOTIFY_CALLBACK pCallback,
                &fdoData->CmNotificationHandle // PHCMNOTIFICATION pNotifyContext
                );
    if (cmRet != CR_SUCCESS) {
        MyKdPrint( ("CM_Register_Notification failed, error %d\n", cmRet));
        status = STATUS_UNSUCCESSFUL;
        return status;
    }

O sistema chama a rotina de retorno de chamada de notificação do driver local sempre que a interface do dispositivo especificada chega ou é removida. A rotina de retorno de chamada pode examinar o parâmetro EventData para determinar qual interface de dispositivo chegou. Em seguida, ele pode enfileirar um item de trabalho para abrir a interface do dispositivo.

DWORD 
MyCmInterfaceNotification(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    )
{
    PFDO_DATA fdoData;
    UNICODE_STRING name;
    WDFDEVICE device;
    NTSTATUS status;
    WDFWORKITEM workitem;

    UNREFERENCED_PARAMETER(hNotify);
    UNREFERENCED_PARAMETER(EventDataSize);

    device = (WDFDEVICE) Context;
    fdoData = ToasterFdoGetData(device);

    switch(Action) {
    case CM_NOTIFY_ACTION_DEVICEINTERFACEARRIVAL: 
        MyKdPrint( ("MyCmInterfaceNotification: Arrival of %S\n",
            EventData->u.DeviceInterface.SymbolicLink));

        //
        // Enqueue a work item to open target
        //

        break;
    case CM_NOTIFY_ACTION_DEVICEINTERFACEREMOVAL: 
        MyKdPrint( ("MyCmInterfaceNotification: removal of %S\n",
            EventData->u.DeviceInterface.SymbolicLink));
        break;
    default:
        MyKdPrint( ("MyCmInterfaceNotification: Arrival unknown action\n"));
        break;
    }

    return 0;
}

A partir da função de retorno de chamada do item de trabalho, o driver local chama WdfIoTargetCreate para criar o destino remoto e WdfIoTargetOpen para abrir um destino de E/S remoto.

Ao chamar WdfIoTargetOpen, o driver opcionalmente registra um EvtIoTargetQueryRemove função de retorno de chamada para receber notificação de remoção, juntamente com a oportunidade de recusar a remoção. Se o driver não fornecer EvtIoTargetQueryRemove, a estrutura fechará o destino de E/S quando o dispositivo for removido.

Em casos raros, um driver UMDF 2 pode chamar CM_Register_Notification uma segunda vez, para se registar para notificações de retirada do dispositivo. Por exemplo, se o driver chamar CreateFile para obter um HANDLE para a interface do dispositivo, deve registar-se para receber notificações de remoção do dispositivo para que possa responder corretamente às tentativas de remoção em consulta. Na maioria dos casos, o driver UMDF 2 chama CM_Register_Notification apenas uma vez e depende do suporte WDF para remoção de dispositivos.
```
VOID 
EvtWorkItem(
    _In_ WDFWORKITEM WorkItem
)
{
    // 
    // create and open remote target
    //

    return;
}
```

Registo para Notificação de Chegada da Interface de Dispositivo e Remoção do Dispositivo

Feedback

Esta página foi útil?

Last updated on 2025-03-30