Spazio contesto oggetto framework

Lo spazio del contesto dell'oggetto è uno spazio di memoria aggiuntivo, non di paging, che un driver può allocare e assegnare a un oggetto. Ogni driver basato su framework può creare uno o più spazi di contesto specifici dell'oggetto per ogni oggetto framework ricevuto o creato dal driver.

I driver basati su framework devono archiviare tutti i dati specifici dell'oggetto, in base al valore o al puntatore, all'interno dello spazio di contesto dell'oggetto a cui appartengono i dati.

Ad esempio, un driver per i dispositivi USB potrebbe creare spazio di contesto per i relativi oggetti dispositivo framework. Nello spazio di contesto, il driver potrebbe archiviare tali informazioni specifiche del dispositivo come le strutture USB_DEVICE_DESCRIPTOR e USB_CONFIGURATION_DESCRIPTOR del dispositivo, oltre a un handle per un oggetto raccolta che rappresenta le pipe dell'interfaccia del dispositivo.

Il framework non passa oggetti framework da un driver a un altro, pertanto non è possibile usare lo spazio di contesto di un oggetto per passare i dati tra due driver.

Per definire lo spazio di contesto di un oggetto, è necessario creare una o più strutture. Ogni struttura rappresenta uno spazio di contesto separato. Il driver userà ogni membro della struttura per archiviare una parte di informazioni specifiche dell'oggetto. Inoltre, il driver deve chiedere al framework di generare un metodo della funzione di accesso per ogni struttura. Questo metodo di accesso accetta un handle di oggetto come input e restituisce l'indirizzo dello spazio di contesto dell'oggetto.

Ogni volta che il driver chiama un metodo di creazione di oggetti, ad esempio WdfDeviceCreate, il metodo alloca facoltativamente lo spazio del contesto. Tutti i metodi di creazione di oggetti accettano una struttura facoltativa WDF_OBJECT_ATTRIBUTES come input. Questa struttura descrive lo spazio di contesto da allocare per l'oggetto.

Per aggiungere ulteriore spazio di contesto a un oggetto dopo che il driver ha chiamato il metodo di creazione dell'oggetto, il driver può chiamare il metodo WdfObjectAllocateContext , che, come i metodi di creazione dell'oggetto, accetta una struttura WDF_OBJECT_ATTRIBUTES come input.

Quando il framework alloca lo spazio di contesto per un oggetto, inizializza anche lo spazio del contesto.

Quando il framework o un driver elimina un oggetto framework, il framework elimina tutto lo spazio di contesto dell'oggetto.

Se il driver usa lo spazio di contesto per archiviare puntatori ai buffer allocati dal driver quando crea un oggetto, il driver deve fornire una funzione EvtCleanupCallback che dealloca i buffer quando l'oggetto viene eliminato.

Per definire la struttura dello spazio di contesto di un oggetto e il metodo di accesso per gli oggetti creati dal driver, il driver deve seguire questa procedura:

  1. Definire una struttura che descrive i dati da archiviare. Ad esempio, se si vogliono creare dati di contesto per gli oggetti dispositivo del driver, il driver potrebbe definire una struttura denominata MY_DEVICE_CONTEXT.

  2. Utilizzare la macro WDF_DECLARE_CONTEXT_TYPE o la macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME . Entrambe queste macro eseguono le operazioni seguenti:

    • Creare e inizializzare una struttura WDF_OBJECT_CONTEXT_TYPE_INFO .
    • Definire un metodo di accesso che il driver userà in un secondo momento per accedere allo spazio di contesto di un oggetto. Il valore restituito del metodo di accesso è un puntatore allo spazio di contesto dell'oggetto.

    La macro WDF_DECLARE_CONTEXT_TYPE crea il nome del metodo della funzione di accesso dal nome della struttura. Ad esempio, se il nome della struttura di contesto è MY_DEVICE_CONTEXT, la macro crea un metodo di accesso denominato WdfObjectGet_MY_DEVICE_CONTEXT.

    La macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME consente di specificare il nome del metodo della funzione di accesso. Ad esempio, è possibile specificare GetMyDeviceContext come nome per il metodo della funzione di accesso al contesto per gli oggetti dispositivo.

  3. Chiamare WDF_OBJECT_ATTRIBUTES_INIT per inizializzare la struttura WDF_OBJECT_ATTRIBUTES dell'oggetto.

  4. Utilizzare la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE per impostare il membro ContextTypeInfo della struttura WDF_OBJECT_ATTRIBUTES sull'indirizzo della struttura WDF_OBJECT_CONTEXT_TYPE_INFO.

  5. Chiamare un metodo di creazione di oggetti, ad esempio WdfDeviceCreate.

Dopo che il driver ha creato un oggetto, il driver può chiamare WdfObjectAllocateContext in qualsiasi momento per aggiungere ulteriore spazio di contesto all'oggetto.

Poiché i passaggi 1 e 2 definiscono strutture di dati globali e creano una routine chiamabile tramite driver, il driver deve completare questi passaggi in un'area del driver che dichiara i dati globali, in genere un file di intestazione. Questi passaggi non devono essere completati dalle routine del driver.

Il driver deve completare i passaggi 3, 4 e 5 dall'interno di una routine del driver che crea un oggetto, ad esempio una funzione di callback EvtDriverDeviceAdd che chiama WdfDeviceCreate.

Il framework può creare due tipi di oggetti, ovvero oggetti richiesta framework e oggetti file del framework, per conto del driver. Il driver può registrare lo spazio di contesto per questi oggetti chiamando rispettivamente WdfDeviceInitSetRequestAttributes e WdfDeviceInitSetFileObjectConfig. Il driver può anche chiamare WdfObjectAllocateContext per allocare spazio di contesto per questi oggetti.

Dopo aver creato un oggetto, il driver può ottenere un puntatore allo spazio di contesto dell'oggetto usando una delle tecniche seguenti:

Se il driver ha un puntatore dello spazio di contesto, può trovare l'oggetto a cui appartiene lo spazio di contesto chiamando WdfObjectContextGetObject.