Frameworkdateiobjekte

Wenn eine Anwendung oder ein Treiber versucht, auf ein Gerät zuzugreifen, in der Regel durch Erstellen oder Öffnen einer Datei, sendet das Betriebssystem eine Anforderung zur Dateierstellung an den Treiberstapel. Wenn die Anwendung oder der Treiber die Verwendung des Geräts abgeschlossen hat, sendet das System dateibereinigungs- und schließen-Anforderungen an den Treiberstapel. Die Anforderungstypen dieser drei Anforderungen sind WdfRequestTypeCreate, WdfRequestTypeCleanup und WdfRequestTypeClose.

Wenn Ihr Treiber WdfDeviceInitSetExclusive nicht aufgerufen hat, muss der Treiber in der Regel dateispezifische oder andere zugriffsspezifische Vorgänge ausführen, wenn er Anforderungen zum Erstellen, Bereinigen und Schließen von Dateien empfängt, da mehrere Dateien gleichzeitig geöffnet werden können oder mehrere Anwendungen gleichzeitig auf das Gerät zugreifen können. Der Treiber muss daher die E/A-Anforderungen nachverfolgen, die jeder Datei oder Anwendung zugeordnet sind.

Das Framework definiert Frameworkdateiobjekte, die die Mittel einer Anwendung oder eines Treibers für den Zugriff auf ein Gerät darstellen, z. B. eine Datei, ein Verzeichnis, ein Volume, einen E-Mail-Slot, eine Named Pipe oder das gesamte Gerät. Ein Dateiname kann einem Dateiobjekt zugeordnet werden, aber die Bedeutung eines Dateinamens ist treiberspezifisch. Weitere Informationen zu Dateinamen finden Sie unter Steuern des Gerätenamespacezugriffs.

Wenn Ihr Treiber Dateivorgänge verarbeiten muss, muss er WdfDeviceInitSetFileObjectConfig innerhalb seiner Rückruffunktion EvtDriverDeviceAdd aufrufen. Die WdfDeviceInitSetFileObjectConfig-Methode empfängt eine WDF_FILEOBJECT_CONFIG-Struktur als Eingabe. Der Treiber verwendet diese Struktur, um seine Rückruffunktionen EvtDeviceFileCreate, EvtFileCleanup und EvtFileClose zu registrieren und optional anzugeben, ob das Framework jedes Mal ein Frameworkdateiobjekt erstellen soll, wenn der Treiber eine Dateierstellungsanforderung empfängt.

Die meisten Treiber, die Dateivorgänge verarbeiten, speichern dateispezifische Informationen im Kontextbereich des Frameworkdateiobjekts. Wenn Ihr Treiber Dateivorgänge verarbeitet, aber keine Informationen im Kontextbereich eines Dateiobjekts speichern muss, muss das Framework keine Frameworkdateiobjekte für den Treiber erstellen.

Erstellen oder Öffnen einer Datei

Wenn das Framework eine Dateierstellungsanforderung für Ihren Funktionstreiber empfängt, wird Folgendes ausgeführt:

1. Erstellt ein Frameworkdateiobjekt, das die Datei darstellt, es sei denn, der Treiber hat zuvor angegeben, dass er keine Frameworkdateiobjekte verwenden muss.

2. Ruft die Rückruffunktion EvtDeviceFileCreate Ihres Treibers auf, wenn der Treiber die Rückruffunktion registriert hat.

Die Rückruffunktion EvtDeviceFileCreate ruft in der Regel Informationen über die Datei ab, z. B. den Namen und die Dateiobjektflags. Der Treiber speichert diese Informationen in der Regel im Kontextbereich des Frameworkdateiobjekts.

Anstatt eine EvtDeviceFileCreate-Rückruffunktion bereitzustellen, kann der Treiber WdfDeviceConfigureRequestDispatching aufrufen, um eine E/A-Warteschlange festzulegen, um alle Dateierstellungsanforderungen (WdfRequestTypeCreate-Anforderungstyp ) zu empfangen. Der Treiber empfängt anschließend Dateierstellungsanforderungen im EvtIoDefault-Anforderungshandler der Warteschlange. (Eine E/A-Warteschlange kann keine Dateierstellungsanforderungen empfangen, wenn das DefaultQueue-Element der WDF_IO_QUEUE_CONFIG-Struktur der Warteschlange auf TRUE festgelegt ist.)

Wenn Ihr Treiber keine EvtDeviceFileCreate-Rückruffunktion bereitstellt und keine E/A-Warteschlange für die Verarbeitung von E/A-Anforderungen vom Typ WdfRequestTypeCreate-typisiert einrichtet, wird das Framework:

• Schließt alle Dateierstellungsanforderungen für den Treiber mit dem status Wert STATUS_SUCCESS ab, wenn ihr Treiber ein Funktionstreiber ist.

• Leitet alle Dateierstellungsanforderungen an den nächstniedrigen Treiber weiter, wenn ihr Treiber ein Filtertreiber ist.

(Wie Sie dieses Verhalten ändern können, finden Sie im Element AutoForwardCleanupClose der WDF_FILEOBJECT_CONFIG-Struktur .)

Hinweis Wenn Ihr Funktionstreiber keine Geräteschnittstellen bereitstellt, die Anwendungen für den Zugriff auf die Geräte des Treibers verwenden können, muss der Treiber eine EvtDeviceFileCreate-Rückruffunktion bereitstellen, die alle Dateierstellungsanforderungen mit einem status-Wert abschließt, für den NT_SUCCESS(status) false entspricht. Andernfalls versucht eine böswillige Anwendung möglicherweise, mithilfe des Namens des physischen Geräteobjekts (PDO) des Geräts auf ein Gerät zuzugreifen. (Alle PDOs haben Namen.)

Wenn ein Treiber eine Erstellungsanforderung an ein E/A-Ziel weiterleitet, darf der Treiber die Anforderung anschließend nicht mit einem Fehler status Wert abschließen, es sei denn, der Treiber erhält einen Fehler status Wert vom E/A-Ziel. Andernfalls werden die niedrigeren Treiber nicht benachrichtigt, dass die Erstellungsanforderung fehlgeschlagen ist, und versuchen möglicherweise, so zu arbeiten, als ob die Datei geöffnet wäre.

Wenn ein Treiber eine Erstellungsanforderung an ein E/A-Ziel weiterleitet, kann der Treiber das flag WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET nicht festlegen, wenn das Framework ein Frameworkdateiobjekt für die Erstellungsanforderung erstellt hat. Daher kann der Treiber das WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET-Flag für eine Erstellungsanforderung nicht festlegen, es sei denn, er legt auch das WdfFileObjectNotRequired-Flag fest, da der Treiber das WDFFILEOBJECT nicht sauber kann, falls ein Treiber unterhalb des Stapels die Erstellungsanforderung fehlschlägt. Stattdessen kann der Treiber alle anderen Sendeoptionen verwenden, z. B. asynchrones Senden mit einer Vervollständigungsroutine oder synchrones Senden. In beiden Fällen muss der Treiber WdfRequestComplete aufrufen, wenn er die Kontrolle wiedererlangt.

Wenn ein Treiber eine Erstellungsanforderung mit einem Fehler status abschließt, löscht das Framework das Frameworkdateiobjekt, ruft jedoch nicht die Rückruffunktionen EvtFileCleanup oder EvtFileClose des Treibers auf. Wenn der Treiber daher zusätzlichen objektspezifischen Arbeitsspeicher außerhalb des Kontextbereichs des Dateiobjekts zuweist, muss er eine EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktion bereitstellen, die den zugeordneten Arbeitsspeicher löscht.

Für Windows Vista und höher können Dateierstellungsanforderungen abgebrochen werden. Frühere Versionen des Windows-Betriebssystems unterstützen das Abbrechen von Dateierstellungsanforderungen nicht.

Das System erstellt immer ein WDM-Dateiobjekt (Windows Driver Model) für jede Erstellungsanforderung, die von einer Benutzeranwendung stammt. Wenn ein Treiber eine Erstellungsanforderung sendet, wird möglicherweise kein WDM-Dateiobjekt für die Anforderung erstellt. In der Regel erstellt das Framework kein Frameworkdateiobjekt, wenn kein WDM-Dateiobjekt vorhanden ist. Wenn Ihr Treiber jedoch WdfDeviceInitSetExclusive aufgerufen hat und der Treiber WdfFileObjectWdfCannotUseFsContexts im FileObjectClass-Member der WDF_FILEOBJECT_CONFIG-Struktur festgelegt hat, erstellt das Framework ein Frameworkdateiobjekt, auch wenn kein WDM-Dateiobjekt vorhanden ist.

Abrufen von Dateiinformationen

Die EvtDeviceFileCreate-Rückruffunktion des Treibers kann eine oder mehrere der folgenden Objektmethoden aufrufen, um Informationen über den Zugriff einer Anwendung oder des Treibers auf ein Gerät zu erhalten:

WdfFileObjectGetFileName
Gibt den Dateinamen zurück, der in einem Frameworkdateiobjekt enthalten ist.

WdfFileObjectGetFlags
Gibt die Flags zurück, die in einem Frameworkdateiobjekt enthalten sind.

WdfFileObjectWdmGetFileObject
Gibt das WDM-Dateiobjekt zurück, das einem Frameworkdateiobjekt zugeordnet ist.

WdfRequestGetParameters
Ruft die Parameter ab, die einem Frameworkanforderungsobjekt zugeordnet sind. Wenn der AnforderungstypWdfRequestTypeCreate ist, enthält das Parameters.Create-Element der WDF_REQUEST_PARAMETERS-Struktur Informationen zur Dateierstellungsanforderung.

In der Regel speichert der Treiber Dateiinformationen im Kontextbereich des Frameworkdateiobjekts. Wenn Ihr Treiber eine E/A-Anforderung von einem abruft, wenn dessen E/A-Warteschlangen vorhanden sind, kann der Treiber WdfRequestGetFileObject aufrufen, um ein Handle für das Frameworkdateiobjekt abzurufen, das der Anforderung zugeordnet ist. Der Treiber kann dann die Dateiinformationen abrufen, die er im Kontextbereich des Frameworkdateiobjekts gespeichert hat.

Ihr Treiber kann eine E/A-Warteschlange nach Anforderungen durchsuchen, die einer bestimmten Datei zugeordnet sind, indem er WdfIoQueueRetrieveRequestByFileObject aufruft.

Wenn ihr Treiber über einen Zeiger auf eine WDM-DEVICE_OBJECT-Struktur verfügt, kann der Treiber WdfDeviceGetFileObject aufrufen, um ein Handle für das Frameworkdateiobjekt abzurufen, das dem WDM-Geräteobjekt zugeordnet ist.

Schließen einer Datei

Wenn eine Anwendung oder ein anderer Treiber eine Datei schließt, empfängt das Framework eine Bereinigungsanforderung und eine Close-Anforderung für Ihren Treiber. Das Framework:

1. Ruft die Rückruffunktionen EvtFileCleanup und EvtFileClose Ihres Treibers auf, wenn der Treiber diese Rückruffunktionen registriert hat.

2. Löscht das Frameworkdateiobjekt, das die Datei darstellt.

Die Rückruffunktionen EvtFileCleanup und EvtFileClose des Treibers erhalten ein Handle für das Frameworkdateiobjekt. Der Treiber kann WdfFileObjectGetDevice aufrufen, um zu bestimmen, welches Framework-Geräteobjekt dem Frameworkdateiobjekt zugeordnet ist.