Oggetti file framework

Quando un'applicazione o un driver tenta di accedere a un dispositivo, in genere creando o aprendo un file, il sistema operativo invia una richiesta di creazione di file allo stack di driver. Al termine dell'uso del dispositivo da parte dell'applicazione o del driver, il sistema invia la pulizia dei file e chiude le richieste allo stack di driver. I tipi di richiesta di queste tre richieste sono rispettivamente WdfRequestTypeCreate, WdfRequestTypeCleanup e WdfRequestTypeClose.

In genere, a meno che il driver non abbia chiamato WdfDeviceInitSetExclusive, il driver deve eseguire operazioni specifiche del file o altre operazioni specifiche dell'accesso quando riceve la creazione, la pulizia e la chiusura di file, perché più file possono essere aperti contemporaneamente o più applicazioni possono accedere al dispositivo contemporaneamente. Il driver deve quindi tenere traccia delle richieste di I/O associate a ogni file o applicazione.

Il framework definisce gli oggetti file del framework, che rappresentano i mezzi di un'applicazione o di un driver per accedere a un dispositivo, ad esempio un file, una directory, un volume, uno slot di posta elettronica, una named pipe o l'intero dispositivo. Un nome file può essere associato a un oggetto file, ma il significato di un nome file è specifico del driver. Per altre informazioni sui nomi di file, vedere Controllo dell'accesso agli spazi dei nomi dei dispositivi.

Se il driver deve gestire le operazioni di file, deve chiamare WdfDeviceInitSetFileObjectConfig dalla relativa funzione di callback EvtDriverDeviceAdd . Il metodo WdfDeviceInitSetFileObjectConfig riceve una struttura WDF_FILEOBJECT_CONFIG come input. Il driver usa questa struttura per registrare le funzioni di callback EvtDeviceFileCreate, EvtFileCleanup e EvtFileClose e, facoltativamente, per indicare se il framework deve creare un oggetto file framework ogni volta che il driver riceve una richiesta di creazione di file.

La maggior parte dei driver che gestiscono le operazioni sui file archivia informazioni specifiche del file nello spazio di contesto dell'oggetto file framework. Se il driver gestisce le operazioni sui file ma non deve archiviare informazioni nello spazio di contesto di un oggetto file, il framework non deve creare oggetti file framework per il driver.

Creazione o apertura di un file

Quando il framework riceve una richiesta di creazione di file per il driver di funzione, è possibile:

1. Crea un oggetto file framework che rappresenta il file, a meno che il driver in precedenza non indica che non sia necessario utilizzare oggetti file framework.

2. Chiama la funzione di callback EvtDeviceFileCreate del driver, se questa è stata registrata.

La funzione di callback EvtDeviceFileCreatein genere ottiene informazioni sul file, ad esempio il nome e i flag dell'oggetto file. Il driver archivia in genere queste informazioni nello spazio di contesto dell'oggetto file framework.

Invece di fornire una funzione di callback EvtDeviceFileCreate , il driver può chiamare WdfDeviceConfigureRequestDispatching per impostare una coda di I/O per ricevere tutte le richieste di creazione di file (tipo di richiesta WdfRequestTypeCreate ). Il driver riceverà successivamente richieste di creazione di file nel gestore della richiesta EvtIoDefault della coda. Una coda di I/O non può ricevere richieste di creazione di file se il membro DefaultQueue della struttura WDF_IO_QUEUE_CONFIG della coda è impostato su TRUE.

Se il driver non fornisce una funzione di callback EvtDeviceFileCreate e non configura una coda di I/O per gestire le richieste di I/O di tipo WdfRequestTypeCreate, il framework:

• Completa tutte le richieste di creazione di file per il driver con un valore di stato STATUS_SUCCESS, se il driver è un driver di funzione.

• Inoltra tutte le richieste di creazione di file al driver inferiore successivo, se il driver è un driver di filtro.

Per vedere come modificare questo comportamento, vedere il membro AutoForwardCleanupClose della struttura WDF_FILEOBJECT_CONFIG .

Nota Se il driver di funzione non fornisce interfacce di dispositivo che le applicazioni possono usare per accedere ai dispositivi del driver, il driver deve fornire una funzione di callback EvtDeviceFileCreate che completa tutte le richieste di creazione di file con un valore di stato per il quale NT_SUCCESS(status) è uguale a FALSE. In caso contrario, un'applicazione dannosa potrebbe tentare di accedere a un dispositivo usando il nome dell'oggetto dispositivo fisico (PDO) del dispositivo. Tutti i PDO hanno nomi.

Se un driver inoltra una richiesta di creazione a una destinazione di I/O, il driver non deve successivamente completare la richiesta con un valore di stato di errore a meno che il driver non riceva un valore di stato di errore dalla destinazione di I/O. In caso contrario, i driver inferiori non riceveranno una notifica che indica che la richiesta di creazione non è riuscita e potrebbe tentare di funzionare come se il file fosse aperto.

Se un driver inoltra una richiesta di creazione a una destinazione di I/O, il driver non può impostare il flag WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET se il framework ha creato un oggetto file framework per la richiesta di creazione. Pertanto, il driver non può impostare il flag di WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET per una richiesta di creazione, a meno che non imposti anche il flag WdfFileObjectNotRequired perché il driver non sarà in grado di pulire il WDFFILEOBJECT nel caso in cui un driver inferiore nello stack non riesca la richiesta di creazione. Al contrario, il driver può usare qualsiasi altra opzione di invio, ad esempio, inviare in modo asincrono con una routine di completamento o inviare in modo sincrono. In entrambi i casi, il driver deve chiamare WdfRequestComplete quando recupera il controllo.

Si noti che se un driver completa una richiesta di creazione con uno stato di errore, il framework elimina l'oggetto file framework ma non chiama le funzioni di callback EvtFileCleanup o EvtFileClose del driver. Pertanto, se il driver alloca memoria aggiuntiva specifica dell'oggetto all'esterno dello spazio di contesto dell'oggetto file, deve fornire una funzione di callback EvtCleanupCallback o EvtDestroyCallback che elimina la memoria allocata.

Per Windows Vista e versioni successive, le richieste di creazione di file possono essere annullate. Le versioni precedenti del sistema operativo Windows non supportano l'annullamento delle richieste di creazione di file.

Il sistema crea sempre un oggetto file WDM (Windows Driver Model) per ogni richiesta di creazione proveniente da un'applicazione utente. Se un driver invia una richiesta di creazione, potrebbe non creare un oggetto file WDM per la richiesta. In genere, il framework non crea un oggetto file framework se non è presente un oggetto file WDM. Tuttavia, se il driver ha chiamato WdfDeviceInitSetExclusive e se il driver ha impostato WdfFileObjectWdfCannotUseFsContexts nel membro FileObjectClass della struttura WDF_FILEOBJECT_CONFIG , il framework creerà un oggetto file framework anche se non esiste un oggetto file WDM.

Recupero di informazioni sui file

La funzione di callback EvtDeviceFileCreate del driver può chiamare uno o più dei metodi di oggetto seguenti per ottenere informazioni sull'accesso di un'applicazione o di un driver a un dispositivo:

WdfFileObjectGetFileName
Restituisce il nome file contenuto in un oggetto file framework.

WdfFileObjectGetFlags
Restituisce i flag contenuti all'interno di un oggetto file framework.

WdfFileObjectWdmGetFileObject
Restituisce l'oggetto file WDM associato a un oggetto file framework.

WdfRequestGetParameters
Recupera i parametri associati a un oggetto richiesta framework. Se il tipo di richiesta è WdfRequestTypeCreate, il membro Parameters.Create della struttura WDF_REQUEST_PARAMETERS contiene informazioni sulla richiesta di creazione del file.

In genere, il driver archivia le informazioni sui file nello spazio di contesto dell'oggetto file framework. Quando il driver ottiene una richiesta di I/O da una delle sue code di I/O, il driver può chiamare WdfRequestGetFileObject per ottenere un handle dell'oggetto file del framework associato alla richiesta. Il driver può quindi recuperare le informazioni sul file archiviate nello spazio di contesto dell'oggetto file framework.

Il driver può cercare in una coda di I/O le richieste associate a un determinato file chiamando WdfIoQueueRetrieveRequestByFileObject.

Se il driver ha un puntatore a una struttura di DEVICE_OBJECT WDM, il driver può chiamare WdfDeviceGetFileObject per ottenere un handle per l'oggetto file framework associato all'oggetto dispositivo WDM.

Chiusura di un file

Quando un'applicazione o un altro driver chiude un file, il framework riceve una richiesta di pulizia e una richiesta di chiusura per il driver. Framework:

1. Chiama le funzioni di callback EvtFileCleanup e EvtFileClose del driver, se il driver ha registrato queste funzioni di callback.

2. Elimina l'oggetto file framework che rappresenta il file.

Le funzioni di callback EvtFileCleanup e EvtFileClose del driver ricevono un handle per l'oggetto file framework. Il driver può chiamare WdfFileObjectGetDevice per determinare quale oggetto dispositivo framework è associato all'oggetto file del framework.