Udostępnij przez

Korzystanie z interfejsów urządzeń (WDF)

Interfejs urządzenia to symboliczny link do urządzenia Plug and Play (PnP), którego aplikacja może używać do uzyskiwania dostępu do urządzenia. Aplikacja w trybie użytkownika może przekazać nazwę linku symbolicznego interfejsu do elementu interfejsu API, takiego jak funkcja CreateFile platformy Microsoft Win32. Aby uzyskać nazwę linku symbolicznego interfejsu urządzenia, aplikacja trybu użytkownika może wywoływać funkcje menedżera konfiguracji lub funkcje SetupApi. Aby uzyskać więcej informacji, zobacz Wyliczanie zainstalowanych interfejsów urządzeń.

Każdy interfejs urządzenia należy do klasy interfejsu urządzenia. Na przykład stos sterowników dla urządzenia CD-ROM może zapewnić interfejs należący do klasy GUID_DEVINTERFACE_CDROM. Jeden z sterowników urządzenia CD-ROM zarejestrowałby wystąpienie klasy GUID_DEVINTERFACE_CDROM w celu poinformowania systemu i aplikacji o dostępności urządzenia CD-ROM. Aby uzyskać więcej informacji na temat klas interfejsów urządzeń, zobacz Omówienie klas interfejsów urządzeń.

Rejestrowanie interfejsu urządzenia

Aby zarejestrować wystąpienie klasy interfejsu urządzenia, sterownik oparty na strukturze może wywołać element WdfDeviceCreateDeviceInterface przed uruchomieniem lub po uruchomieniu urządzenia. Jeśli sterownik obsługuje wiele wystąpień interfejsu, może przypisać unikatowy ciąg odwołania do każdego wystąpienia.

Po zarejestrowaniu interfejsu urządzenia sterownik może wywołać metodę WdfDeviceRetrieveDeviceInterfaceString , aby uzyskać symboliczną nazwę łącza przypisaną przez system do interfejsu urządzenia.

Aby uzyskać informacje o innych sposobach rejestrowania interfejsów urządzeń przez sterowniki, zobacz Rejestrowanie klasy interfejsu urządzenia.

Włączanie i wyłączanie interfejsu urządzenia

Interfejsy utworzone przed uruchomieniem urządzenia (na przykład z EvtDriverDeviceAdd, EvtChildListCreateDevice lub EvtDevicePrepareHardware) są automatycznie włączane przez platformę, gdy urządzenie przechodzi przez wyliczenie PnP i uruchamia się. Aby zapobiec automatycznemu włączeniu interfejsu podczas uruchamiania PnP, przed uruchomieniem pnP wywołaj element WdfDeviceSetDeviceInterfaceStateEx z tej samej funkcji wywołania zwrotnego (ustaw parametr EnableInterface na FALSE) dla tego interfejsu.

Interfejsy utworzone po uruchomieniu urządzenia nie zostaną automatycznie włączone. Sterownik musi wywołać element WdfDeviceSetDeviceInterfaceState lub WdfDeviceSetDeviceInterfaceStateEx , aby włączyć takie interfejsy.

Wszystkie interfejsy są automatycznie wyłączone, gdy urządzenie zostanie usunięte z systemu PnP. Należy pamiętać, że żadne zmiany stanu zasilania urządzenia lub ponowne równoważenie zasobu PnP nie zmienia stanu interfejsu.

Sterownik może w razie potrzeby wyłączyć i ponownie włączyć interfejs urządzenia. Jeśli na przykład sterownik ustali, że jego urządzenie przestało odpowiadać, sterownik może wywołać metodę WdfDeviceSetDeviceInterfaceState lub WdfDeviceSetDeviceInterfaceStateEx , aby wyłączyć interfejsy urządzenia i uniemożliwić aplikacjom uzyskanie nowych dojść do interfejsu. (Nie ma to wpływu na istniejące dojścia do interfejsu). Jeśli urządzenie później stanie się dostępne, sterownik może wywołać element WdfDeviceSetDeviceInterfaceState lub WdfDeviceSetDeviceInterfaceStateEx ponownie, aby ponownie włączyć interfejsy.

Odbieranie żądań dostępu do interfejsu urządzenia

Kiedy składnik aplikacji lub tryb jądra żąda dostępu do interface'u urządzenia sterownika, platforma wywołuje funkcję zwrotną sterownika EvtDeviceFileCreate. Sterownik może wywołać element WdfFileObjectGetFileName , aby uzyskać nazwę urządzenia lub pliku, do którego uzyskuje dostęp składnik aplikacji lub trybu jądra. Jeśli sterownik określił ciąg odwołania podczas rejestrowania interfejsu urządzenia, system operacyjny zawiera ciąg odwołania w pliku lub nazwie urządzenia, które zwraca WdfFileObjectGetFileName .

Uzyskiwanie dostępu do interfejsu urządzenia innego sterownika

W tej sekcji pokazano, jak sterownik Kernel-Mode Driver Framework (KMDF) lub sterownik User-Mode Driver Framework (UMDF) w wersji 2 rejestruje się w celu powiadomienia o przybyciu lub usunięciu interfejsu urządzenia dostarczonego przez inny sterownik, a następnie tworzy zdalny element docelowy we/ wy do komunikowania się z urządzeniem reprezentowanym przez interfejs urządzenia.

Aby uzyskać informacje na temat tego, jak to zrobić w sterowniku UMDF w wersji 1, zobacz Using Device Interfaces in UMDF Drivers (Używanie interfejsów urządzeń w sterownikach UMDF).

Aby zarejestrować się w celu otrzymywania powiadomień o zdarzeniach interfejsu urządzenia, sterownik KMDF wywołuje funkcję IoRegisterPlugPlayNotification, podczas gdy sterownik UMDF 2 wywołuje CM_Register_Notification. W obu przypadkach sterownik wywołuje odpowiednią procedurę z funkcji EvtDriverDeviceAdd callback.

Poniższy przykład kodu pokazuje, jak lokalny sterownik UMDF 2 rejestruje powiadomienia, a następnie otwiera zdalny element docelowy we/wy.

  1. Sterownik zdalny rejestruje się w interfejsie urządzenia, wywołując polecenie WdfDeviceCreateDeviceInterface z 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;
    }

  2. Sterownik lokalny wywołuje CM_Register_Notification z EvtDriverDeviceAdd , aby zarejestrować się w celu otrzymywania powiadomień, gdy interfejs urządzenia jest dostępny. Podaj wskaźnik do procedury wywołania zwrotnego powiadomień, którą platforma wywołuje, gdy są dostępne interfejsy urządzeń.

    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;
    }

  3. System wywołuje procedurę wywołania zwrotnego powiadomień lokalnego sterownika za każdym razem, gdy określony interfejs urządzenia zostaje dodany lub usunięty. Funkcja wywołania zwrotnego może zbadać parametr EventData, aby określić, który interfejs urządzenia się pojawił. Następnie może ustawić element roboczy w kolejce, aby otworzyć interfejs urządzenia.

    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;
}

  4. Za pomocą funkcji wywołania zwrotnego elementu roboczego, sterownik lokalny wywołuje WdfIoTargetCreate w celu utworzenia zdalnego obiektu docelowego oraz WdfIoTargetOpen, aby otworzyć zdalny obiekt docelowy I/O.

    Podczas wywoływania funkcji WdfIoTargetOpen sterownik opcjonalnie rejestruje funkcję wywołania zwrotnego EvtIoTargetQueryRemove w celu otrzymania powiadomienia o usunięciu wraz z możliwością odrzucenia usunięcia. Jeśli sterownik nie udostępnia EvtIoTargetQueryRemove, struktura zamyka obiekt docelowy we/wy, gdy urządzenie zostanie usunięte.

    W rzadkich przypadkach sterownik UMDF 2 może wywołać CM_Register_Notification po raz drugi, aby zarejestrować się w celu powiadomienia o usunięciu urządzenia. Na przykład, jeśli sterownik wywołuje CreateFile, aby uzyskać Handle do interfejsu urządzenia, powinien zarejestrować się w celu otrzymywania powiadomień o usunięciu urządzenia, aby móc prawidłowo reagować na próby usunięcia urządzenia. W większości przypadków sterownik UMDF 2 wywołuje CM_Register_Notification tylko raz i polega na wsparciu WDF przy usuwaniu urządzenia.

    VOID 
EvtWorkItem(
    _In_ WDFWORKITEM WorkItem
)
{
    // 
    // create and open remote target
    //

    return;
}

Rejestrowanie powiadomień o pojawieniu się interfejsu urządzenia i jego usunięciu

  • Last updated on