Kontextbereich des Frameworkobjekts

Objektkontextbereich ist zusätzlicher, nicht ausstellbarer Speicherplatz, den ein Treiber einem Objekt zuweisen und zuweisen kann. Jeder frameworkbasierte Treiber kann einen oder mehrere objektspezifische Kontexträume für jedes Frameworkobjekt erstellen, das der Treiber empfängt oder erstellt.

Frameworkbasierte Treiber sollten alle objektspezifischen Daten, entweder nach Wert oder nach Zeiger, innerhalb des Kontextraums des Objekts speichern, zu dem die Daten gehören.

Beispielsweise kann ein Treiber für USB-Geräte Kontextbereich für seine Frameworkgeräteobjekte erstellen. Im Kontextbereich speichert der Treiber möglicherweise gerätespezifische Informationen wie die USB_DEVICE_DESCRIPTOR - und USB_CONFIGURATION_DESCRIPTOR-Strukturen des Geräts sowie ein Handle für ein Sammlungsobjekt , das die Pipes einer Geräteschnittstelle darstellt.

Das Framework übergibt keine Frameworkobjekte von einem Treiber an einen anderen, sodass Sie den Kontextbereich eines Objekts nicht verwenden können, um Daten zwischen zwei Treibern zu übergeben.

Um den Kontextraum eines Objekts zu definieren, müssen Sie mindestens eine Struktur erstellen. Jede Struktur stellt einen separaten Kontextraum dar. Ihr Treiber verwendet jedes Strukturelement, um objektspezifische Informationen zu speichern. Darüber hinaus muss Ihr Treiber das Framework bitten, eine Accessormethode für jede Struktur zu generieren. Diese Accessormethode akzeptiert ein Objekthandle als Eingabe und gibt die Adresse des Kontextraums des Objekts zurück.

Wenn Ihr Treiber eine Objekterstellungsmethode aufruft, z. B. WdfDeviceCreate, weist die Methode optional Kontextraum zu. Alle Objekterstellungsmethoden akzeptieren eine optionale WDF_OBJECT_ATTRIBUTES-Struktur als Eingabe. Diese Struktur beschreibt den Kontextraum, den das Framework dem -Objekt zuordnen soll.

Um einem Objekt zusätzlichen Kontextraum hinzuzufügen, nachdem der Treiber die Erstellungsmethode des Objekts aufgerufen hat, kann der Treiber die WdfObjectAllocateContext-Methode aufrufen, die wie die Methoden zur Objekterstellung eine WDF_OBJECT_ATTRIBUTES Struktur als Eingabe akzeptiert.

Wenn das Framework einen Kontextraum für ein Objekt zuweist, wird auch der Kontextraum null initialisiert.

Wenn entweder das Framework oder ein Treiber ein Framework-Objekt löscht, löscht das Framework den gesamten Kontextraum des Objekts.

Wenn Ihr Treiber Kontextspeicher verwendet, um Zeiger auf Puffer zu speichern, die der Treiber beim Erstellen eines Objekts zuweist, sollte der Treiber eine EvtCleanupCallback-Funktion bereitstellen, die die Puffer beim Löschen des Objekts behandelt.

Um die Kontextraumstruktur eines Objekts und die Accessormethode für die Objekte zu definieren, die Ihr Treiber erstellt, muss Ihr Treiber die folgenden Schritte ausführen:

1. Definieren Sie eine Struktur, die die Daten beschreibt, die Sie speichern möchten. Wenn Sie beispielsweise Kontextdaten für die Geräteobjekte Ihres Treibers erstellen möchten, kann Ihr Treiber eine Struktur namens MY_DEVICE_CONTEXT definieren.

2. Verwenden Sie entweder das makro WDF_DECLARE_CONTEXT_TYPE oder das makro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME . Beide Makros führen folgendes aus:

   • Erstellen und initialisieren Sie eine WDF_OBJECT_CONTEXT_TYPE_INFO-Struktur .
   • Definieren Sie eine Accessormethode, die Ihr Treiber später für den Zugriff auf den Kontextraum eines Objekts verwendet. Der Rückgabewert der Accessormethode ist ein Zeiger auf den Kontextbereich des Objekts.

   Das WDF_DECLARE_CONTEXT_TYPE Makros erstellt den Namen der Accessormethode aus dem Namen Ihrer Struktur. Wenn der Name Ihrer Kontextstruktur beispielsweise MY_DEVICE_CONTEXT ist, erstellt das Makro eine Accessormethode mit dem Namen WdfObjectGet_MY_DEVICE_CONTEXT.

   Mit dem WDF_DECLARE_CONTEXT_TYPE_WITH_NAME Makros können Sie den Namen der Accessormethode angeben. Sie können beispielsweise GetMyDeviceContext als Namen für Ihre Kontextzugriffsmethode für Geräteobjekte angeben.

3. Rufen Sie WDF_OBJECT_ATTRIBUTES_INIT auf, um die WDF_OBJECT_ATTRIBUTES Struktur des Objekts zu initialisieren.

4. Verwenden Sie das Makro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE , um das ContextTypeInfo-Element der WDF_OBJECT_ATTRIBUTES-Struktur auf die Adresse der WDF_OBJECT_CONTEXT_TYPE_INFO-Struktur festzulegen.

5. Rufen Sie eine Objekterstellungsmethode auf, z. B. WdfDeviceCreate.

Nachdem Ihr Treiber ein Objekt erstellt hat, kann der Treiber WdfObjectAllocateContext jederzeit aufrufen, um dem Objekt zusätzlichen Kontextbereich hinzuzufügen.

Da die Schritte 1 und 2 globale Datenstrukturen definieren und eine vom Treiber aufrufbare Routine erstellen, muss Ihr Treiber diese Schritte in einem Bereich des Treibers ausführen, der globale Daten deklariert – in der Regel eine Headerdatei. Diese Schritte dürfen nicht innerhalb der Routinen Ihres Fahrers ausgeführt werden.

Der Treiber muss die Schritte 3, 4 und 5 innerhalb einer Treiberroutine ausführen, die ein Objekt erstellt, z. B. eine EvtDriverDeviceAdd-Rückruffunktion , die WdfDeviceCreate aufruft.

Das Framework kann im Auftrag Ihres Treibers zwei Arten von Objekten erstellen: Frameworkanforderungsobjekte und Frameworkdateiobjekte. Ihr Treiber kann den Kontextbereich für diese Objekte registrieren, indem er WdfDeviceInitSetRequestAttributes bzw . WdfDeviceInitSetFileObjectConfig aufruft. Ihr Treiber kann auch WdfObjectAllocateContext aufrufen, um diesen Objekten Kontextraum zuzuweisen.

Nachdem ein Objekt erstellt wurde, kann der Treiber mithilfe einer der folgenden Techniken einen Zeiger auf den Kontextraum des Objekts abrufen:

• Rufen Sie die Kontextzugriffsmethode auf, die Sie in Schritt 2 der vorherigen Prozedur erstellt haben, indem Sie entweder das WDF_DECLARE_CONTEXT_TYPE - oder das WDF_DECLARE_CONTEXT_TYPE_WITH_NAME-Makro verwenden.

• Rufen Sie WdfObjectGetTypedContext auf, und geben Sie den Namen Ihrer vom Treiber definierten Kontextstruktur an.

Wenn Ihr Treiber über einen Kontextraumzeiger verfügt, kann er das Objekt finden, zu dem der Kontextraum gehört, indem er WdfObjectContextGetObject aufruft.