Apparaatinterfaces gebruiken in UMDF-stuurprogramma's

Een apparaatinterface is een symbolische koppeling naar een Plug and Play-apparaat (PnP) dat een toepassing kan gebruiken voor toegang tot het apparaat. Een toepassing in de gebruikersmodus kan de symbolische koppelingsnaam van de interface doorgeven aan een API-element, zoals de functie Microsoft Win32 CreateFile . Om de symbolische koppelingsnaam van een apparaatinterface te verkrijgen, kan de gebruikersmodustoepassing SetupDi-functies aanroepen. Zie SetupDi Device Interface Functions voor meer informatie over SetupDi-functies.

Elke apparaatinterface behoort tot een apparaatinterfaceklasse. Een stuurprogrammastack voor een CD-ROM apparaat kan bijvoorbeeld een interface bieden die deel uitmaakt van de GUID_DEVINTERFACE_CDROM-klasse. Een van de stuurprogramma's van het CD-ROM apparaat registreert een exemplaar van de GUID_DEVINTERFACE_CDROM-klasse om het systeem en de toepassingen te informeren dat er een CD-ROM apparaat beschikbaar is. Zie Inleiding tot apparaatinterfaces voor meer informatie over apparaatinterfaceklassen.

Een apparaatinterface registreren

Als u een exemplaar van een apparaatinterfaceklasse wilt registreren, kan een op UMDF gebaseerd stuurprogramma IWDFDevice::CreateDeviceInterface aanroepen vanuit de bijbehorende IDriverEntry::OnDeviceAdd callback-functie. Als het stuurprogramma meerdere exemplaren van de interface ondersteunt, kan er een unieke referentietekenreeks aan elk exemplaar worden toegewezen.

Een apparaatinterface in- en uitschakelen

Als het maken slaagt, wordt de interface automatisch ingeschakeld en uitgeschakeld op basis van de PnP-status van het apparaat.

Bovendien kan een stuurprogramma een apparaatinterface indien nodig uitschakelen en opnieuw inschakelen. Als een stuurprogramma bijvoorbeeld bepaalt dat het apparaat niet meer reageert, kan het stuurprogramma IWDFDevice::AssignDeviceInterfaceState aanroepen om de interfaces van het apparaat uit te schakelen en te voorkomen dat toepassingen nieuwe ingangen voor de interface verkrijgen. (Bestaande ingangen voor de interface worden niet beïnvloed.) Als het apparaat later beschikbaar komt, kan het stuurprogramma IWDFDevice::AssignDeviceInterfaceState opnieuw aanroepen om de interfaces opnieuw in te schakelen.

Aanvragen ontvangen voor toegang tot een apparaatinterface

Wanneer een toepassing toegang vraagt tot de apparaatinterface van een stuurprogramma, roept het framework de callbackfunctie IQueueCallbackCreate::OnCreateFile aan. Het stuurprogramma kan IWDFFile::RetrieveFileName aanroepen om de naam te verkrijgen van het apparaat of bestand waartoe de toepassing toegang heeft. Als het stuurprogramma een referentietekenreeks heeft opgegeven bij het registreren van de apparaatinterface, bevat het besturingssysteem de referentietekenreeks in de naam van het bestand of apparaat dat IWDFFile::RetrieveFileName retourneert.

Apparaatevenementen maken

Uw stuurprogramma op basis van UMDF kan apparaatspecifieke, aangepaste gebeurtenissen ( apparaatgebeurtenissen genoemd) maken door IWDFDevice::P ostEvent aan te roepen. Een stuurprogramma dat is geregistreerd om een van de interfaces van het apparaat te gebruiken, kan meldingen ontvangen van de aangepaste gebeurtenissen van een apparaat. Op UMDF gebaseerde stuurprogramma's ontvangen dergelijke meldingen door een IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent callback-functie op te geven.

Aangepaste gebeurtenissen zijn uniek voor het apparaat. Zowel de ontwikkelaar van het stuurprogramma dat de gebeurtenis maakt als de ontwikkelaar van het stuurprogramma dat de gebeurtenis ontvangt, moet de betekenis van de gebeurtenis begrijpen.

Toegang tot de apparaatinterface van een ander stuurprogramma

Als u wilt dat uw op UMDF gebaseerde stuurprogramma I/O-aanvragen verzendt naar een apparaatinterface die een ander stuurprogramma biedt, kunt u een extern I/O-doel maken dat de apparaatinterface vertegenwoordigt.

Ten eerste moet uw stuurprogramma zich registreren om een melding te ontvangen wanneer er een apparaatinterface beschikbaar is. Gebruik de volgende stappen:

1. Wanneer uw stuurprogramma IWDFDriver::CreateDevice aanroept, kan het stuurprogramma een IPnpCallbackRemoteInterfaceNotification-interface bieden. De callbackfunctie IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival van deze interface informeert uw driver wanneer er een apparaatinterface beschikbaar komt.

2. Nadat uw stuurprogramma IWDFDriver::CreateDevice heeft aangeroepen, kan het IWDFDevice2::RegisterRemoteInterfaceNotification aanroepen voor elke apparaatinterface die door het stuurprogramma wordt gebruikt.

Vervolgens roept het framework de IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival callback-functie aan telkens wanneer een opgegeven apparaatinterface beschikbaar komt. De callback-functie kan IWDFRemoteInterfaceInitialize::GetInterfaceGuid en IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink aanroepen om te bepalen welke apparaatinterface is aangekomen.

De functie IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival callback moet doorgaans het volgende doen:

1. Roep IWDFDevice2::CreateRemoteInterface aan om een extern interfaceobject te maken, optioneel met IRemoteInterfaceCallbackEvent- en IRemoteInterfaceCallbackRemoval-interfaces.

2. Roep IWDFDevice2::CreateRemoteTarget aan om een extern doelobject te maken, optioneel met een IRemoteTargetCallbackRemoval-interface.

3. Roep IWDFRemoteTarget::OpenRemoteInterface aan om de apparaatinterface te verbinden met het externe doel.

   Als de apparaatinterface een is die door de SWENUM-softwareapparaat-opsomer wordt gemaakt, moet uw stuurprogramma OpenRemoteInterface aanroepen vanuit een werkitem. (Zie bijvoorbeeld de functie QueueUserWorkItem in de Windows SDK.)

Nu kan het stuurprogramma I/O-aanvragen opmaken en verzenden naar het externe I/O-doel.

Naast de callback-functie IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival, kan een op UMDF gebaseerd stuurprogramma twee extra callback-functies bieden voor het ontvangen van meldingen van apparaatinterfacegebeurtenissen.

• De callbackfunctie IRemoteInterfaceCallbackRemoval::OnRemoteInterfaceRemoval meldt het stuurprogramma wanneer een apparaatinterface wordt verwijderd.

• De callback-functie IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent meldt het stuurprogramma wanneer de aangepaste gebeurtenissen van een apparaat binnenkomen.