Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Een WPD-stuurprogramma (Windows Portable Devices) biedt het communicatiekanaal tussen toepassingen en het fysieke apparaat. Er kunnen op elk gewenst moment meerdere WPD-toepassingen worden uitgevoerd. Het stuurprogramma moet aanvragen van verschillende clients op de computer verwerken en de clients identificeren op basis van de aanvragen in de wachtrij. Met andere woorden, het stuurprogramma heeft een efficiënte en eenvoudige manier nodig om clientgegevens per verbinding op te slaan en de gegevens op aanvraag op te halen.
De User-Mode Driver Frameork (UMDF) ondersteunt deze mogelijkheid met behulp van een contextgebied: een algemeen mechanisme waarin een stuurprogramma clientgegevens opslaat. Een WPD-stuurprogramma moet een gegevensstructuur of -object toewijzen aan de clientgegevens, de gegevensstructuur toewijzen aan het contextgebied voor het frameworkobject en de context op een later tijdstip ophalen.
Het juiste WDF-frameworkobject per verbinding dat moet worden gebruikt, is het WDF-bestandsobject.
Context toewijzen
Het stuurprogramma wijst de context toe wanneer de clientcomputer er een verbinding mee opent.
Wanneer een WPD-toepassing de methode IPortableDevice::Open of de methode IPortableDeviceService::Open aanroept, maakt de WPD-API een handle voor het stuurprogramma met behulp van de Win32-methode CreateFile. Aan de kant van de stuurprogramma initialiseert het User-Mode Driver Framework (UMDF) een IWDFFile-object en stuurt deze, samen met de aanvraag voor het aanmaken, door naar de methode IQueueCallbackCreate::OnCreateFile van het stuurprogramma. Het IWDFFile--object in dit geval vertegenwoordigt een Win32 HANDLE- die wordt gebruikt voor volgende communicatie van deze client naar het stuurprogramma.
U vindt een voorbeeld van een CreateFile callback-implementatie in de CQueue::OnCreateFile methode van de WpdWudfSampleDriver. Een stuurprogrammaspecifiek ContextMap COM-object wordt gebruikt voor het opslaan van clientgegevens (toepassingsnaam, versie, opsomming in voortgang en resourcecontexten, enzovoort). Houd er rekening mee dat het gebruik van COM-objecten als contextgegevens niet vereist is door UMDF; UMDF ziet de contextgegevens als een PVOID-. Als u een COM-object gebruikt om contextgegevens op te slaan, moet uw stuurprogramma het referentieaantal voor dat COM-object behouden en ervoor zorgen dat de resources worden vrijgemaakt in de juiste opschoonmethoden.
Als u contextgegevens wilt opslaan, initialiseert het stuurprogramma een nieuw ContextMap-object en roept het IWDFObject::AssignContext methode aan voor de IWDFFile--object dat door UMDF wordt ingeleverd. De parameters voor deze methode verwijzen naar een object IObjectCleanup en de zojuist gemaakte ContextMap. Het object IObjectCleanup bevat de code voor het opschonen van de context; de zojuist gemaakte kaart bevat de gegevens die worden opgeslagen. Het stuurprogramma roept de methode IObjectCleanup::OnCleanup aan wanneer het bestandsobject tijdens CloseHandle wordt vernietigd.
Daarnaast kan slechts één context worden toegewezen aan het bestandsobject (of aan een UMDF-frameworkobject). Volgende aanroepen naar de methode AssignContext mislukken als er al een context is toegewezen. Als u clientspecifieke gegevens dynamisch wilt toevoegen of verwijderen, kan een stuurprogramma een toewijzingsobject implementeren om de gegevens te beheren en een aanwijzer toe te wijzen aan dat object als context van het bestandsobject. Raadpleeg bijvoorbeeld het ContextMap-object van WpdWudfSampleDriver.
contextgegevens ophalen en opslaan
Voor toegang tot de clientgegevens tijdens verzoeken haalt een WPD stuurprogramma de context op uit het opgegeven IWDFFile-object.
De ophaalvolgorde wordt uitgevoerd door de volgende stappen uit te voeren:
- Het stuurprogramma roept de methode IWDFIoRequest::GetFileObject aan om het IWDFFile--object te verkrijgen.
- Het stuurprogramma roept de methode IWDFObject::RetrieveContext op het IWDFFile--object aan om toegang te krijgen tot het contextgebied. In het voorbeeldstuurprogramma is het contextgebied de aanwijzer naar het ContextMap-object dat is gemaakt in CQueue::OnCreateFile, toen de toepassing IPortableDevice::Openaanriep.
- Het stuurprogramma voegt gegevens toe aan of verwijdert gegevens rechtstreeks uit het ContextMap-object wanneer deze de WPD-opdrachten verwerkt. Telkens wanneer een toepassing verbinding maakt door IPortableDevice aan te roepen::Open, heeft deze een eigen IWDFFile-- en ContextMap-objecten.
Raadpleeg de code van WpdWudfSampleDriver voor voorbeelden van het ophalen van contexttoewijzingen en het toevoegen van clientgegevens. In de volgende tabel wordt beschreven waar u de code kunt vinden in de WpdWudfSampleDriver.
| Voorbeeld | Locatie in voorbeeldstuurprogramma |
|---|---|
| De contextmap ophalen uit het bestandsobject voor het WDF-verzoek. | CQueue::OnDeviceIoControl |
| Clientgegevens toevoegen aan de contextkaart bij het verwerken van de opdracht WPD_COMMAND_COMMON_SAVE_CLIENT_INFORMATION | WpdBaseDriver::OnSaveClientInfo |
Het vrijgeven van de context
Wanneer de clienttoepassing de methode IPortableDevice::Close aanroept, roept de WPD-API op zijn beurt CloseHandle- aan op de Win32-ingang die is gekoppeld aan de open verbinding. Voordat UMDF als reactie op de CloseHandle-het IWDFFile--object vernietigt, roept het de IObjectCleanup::OnCleanup--methode aan die het stuurprogramma heeft doorgegeven aan AssignContext tijdens de OnCreateFile-.
Een voorbeeldimplementatie van de IQueueCleanup callback is de CQueue::OnCleanup methode van de WpdWudfSampleDriver-driver. Met deze methode wordt de ContextMap opgehaald die is opgeslagen in het object IWDFObject (in dit geval het exemplaar van IWDFFile van OnCreateFile) en wordt het toegewezen geheugen vrijgemaakt, inclusief de objecten die de ContextMap bevat. Om geheugenlekken te voorkomen, moet u ervoor zorgen dat de objecten correct worden opgeschoond en (indien van toepassing) het aantal verwijzingen verlagen.