Delen via

Frameworkobject Contextruimte

Objectcontextruimte is extra, niet-pagineerbare geheugenruimte die een stuurprogramma kan toewijzen aan een object. Elk frameworkstuurprogramma kan een of meer objectspecifieke contextruimten maken voor elk frameworkobject dat het stuurprogramma ontvangt of maakt.

Stuurprogramma's op basis van framework moeten alle objectspecifieke gegevens opslaan, hetzij op waarde of op aanwijzer, binnen de contextruimte van het object waartoe de gegevens behoren.

Een stuurprogramma voor USB-apparaten kan bijvoorbeeld contextruimte maken voor de frameworkapparaatobjecten. In de contextruimte kan het stuurprogramma dergelijke apparaatspecifieke informatie opslaan als de USB_DEVICE_DESCRIPTOR - en USB_CONFIGURATION_DESCRIPTOR structuren van het apparaat, plus een ingang voor een verzamelingsobject dat de pijpen van een apparaatinterface vertegenwoordigt.

Het framework geeft geen frameworkobjecten van het ene stuurprogramma naar het andere door, dus u kunt de contextruimte van een object niet gebruiken om gegevens tussen twee stuurprogramma's door te geven.

Als u de contextruimte van een object wilt definiëren, moet u een of meer structuren maken. Elke structuur vertegenwoordigt een afzonderlijke contextruimte. Uw stuurprogramma gebruikt elk structuurlid om een stukje objectspecifieke informatie op te slaan. Daarnaast moet uw stuurprogramma het framework vragen om een accessormethode te genereren voor elke structuur. Deze accessormethode accepteert een objectgreep als invoer en retourneert het adres van de contextruimte van het object.

Wanneer uw stuurprogramma een methode voor het maken van objecten aanroept, zoals WdfDeviceCreate, wijst de methode eventueel contextruimte toe. Alle methoden voor het maken van objecten accepteren een optionele WDF_OBJECT_ATTRIBUTES structuur als invoer. Deze structuur beschrijft de contextruimte die u wilt toewijzen aan het framework voor het object.

Als u extra contextruimte wilt toevoegen aan een object nadat het stuurprogramma de methode voor het maken van het object heeft aangeroepen, kan het stuurprogramma de methode WdfObjectAllocateContext aanroepen. Deze methode accepteert, zoals de methoden voor het maken van objecten, een WDF_OBJECT_ATTRIBUTES structuur als invoer.

Wanneer het framework contextruimte voor een object toewijst, wordt ook de contextruimte met nul geïnitialiseerd.

Wanneer het framework of een stuurprogramma een frameworkobject verwijdert, verwijdert het framework alle contextruimte van het object.

Als uw stuurprogramma contextruimte gebruikt om aanwijzers naar buffers op te slaan die het stuurprogramma toewijst wanneer het een object maakt, moet het stuurprogramma een EvtCleanupCallback-functie opgeven waarmee de buffers worden vrijgemaakt wanneer het object wordt verwijderd.

Als u de contextruimtestructuur en accessormethode van een object wilt definiëren voor de objecten die door het stuurprogramma worden gemaakt, moet uw stuurprogramma de volgende stappen uitvoeren:

  1. Definieer een structuur waarin de gegevens worden beschreven die u wilt opslaan. Als u bijvoorbeeld contextgegevens wilt maken voor de apparaatobjecten van uw stuurprogramma, kan uw stuurprogramma een structuur definiëren met de naam MY_DEVICE_CONTEXT.

  2. Gebruik de macro WDF_DECLARE_CONTEXT_TYPE of de WDF_DECLARE_CONTEXT_TYPE_WITH_NAME macro. Beide macro's doen het volgende:

    • Een WDF_OBJECT_CONTEXT_TYPE_INFO-structuur maken en initialiseren.
    • Definieer een accessormethode die uw stuurprogramma later gaat gebruiken om toegang te krijgen tot de contextruimte van een object. De retourwaarde van de accessormethode is een aanwijzer naar de contextruimte van het object.

    De WDF_DECLARE_CONTEXT_TYPE macro maakt de naam van de accessormethode op basis van de naam van uw structuur. Als de naam van de contextstructuur bijvoorbeeld MY_DEVICE_CONTEXT is, maakt de macro een accessormethode met de naam WdfObjectGet_MY_DEVICE_CONTEXT.

    Met de macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME kunt u de naam van de accessormethode opgeven. U kunt bijvoorbeeld GetMyDeviceContext opgeven als de naam voor de methode voor contexttoegang voor apparaatobjecten.

  3. Roep WDF_OBJECT_ATTRIBUTES_INIT aan om de WDF_OBJECT_ATTRIBUTES structuur van het object te initialiseren.

  4. Gebruik de macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE om het lid ContextTypeInfo van de WDF_OBJECT_ATTRIBUTES structuur in te stellen op het adres van de WDF_OBJECT_CONTEXT_TYPE_INFO-structuur.

  5. Roep een methode voor het maken van objecten aan, zoals WdfDeviceCreate.

Nadat het stuurprogramma een object heeft gemaakt, kan het stuurprogramma WdfObjectAllocateContext op elk gewenst moment aanroepen om extra contextruimte aan het object toe te voegen.

Omdat stap 1 en 2 globale gegevensstructuren definiëren en een aanroepbare routine voor stuurprogramma's maken, moet uw stuurprogramma deze stappen uitvoeren op een gebied van het stuurprogramma dat globale gegevens declareert, meestal een headerbestand. Deze stappen mogen niet worden voltooid vanuit de routines van uw stuurprogramma.

Uw stuurprogramma moet stap 3, 4 en 5 uitvoeren vanuit een stuurprogrammaroutine waarmee een object wordt gemaakt, zoals een EvtDriverDeviceAdd callback-functie die WdfDeviceCreate aanroept.

Het framework kan namens uw stuurprogramma twee typen objecten maken: frameworkaanvraagobjecten en frameworkbestandsobjecten. Uw stuurprogramma kan contextruimte voor deze objecten registreren door respectievelijk WdfDeviceInitSetRequestAttributes en WdfDeviceSetFileObjectConfig aan te roepen. Uw stuurprogramma kan ook WdfObjectAllocateContext aanroepen om contextruimte voor deze objecten toe te wijzen.

Nadat een object is gemaakt, kan het stuurprogramma een aanwijzer verkrijgen naar de contextruimte van het object met behulp van een van de volgende technieken:

Als uw stuurprogramma een contextruimteaanwijzer heeft, kan het object worden gevonden waartoe de contextruimte behoort door WdfObjectContextGetObject aan te roepen.

  • Last updated on