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'applicazione o del driver usando il dispositivo, il sistema invia la pulizia del 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 per l'accesso quando riceve la creazione, la pulizia e la chiusura dei file, perché più file possono essere aperti simultaneamente o più applicazioni possono accedere contemporaneamente al dispositivo. 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 un'applicazione o un driver significa accedere a un dispositivo, ad esempio un file, una directory, un volume, uno slot di posta elettronica, una pipe denominata 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 dei file, vedere Controllo dell'accesso dello spazio dei nomi dei dispositivi.

Se il driver deve gestire le operazioni di file, deve chiamare WdfDeviceInitSetFileObjectConfig dall'interno della relativa funzione di callback EvtDriverDeviceAdd callback. Il metodo WdfDeviceInitSetFileObjectConfig riceve una struttura WDF_FILEOBJECT_CONFIG come input. Il driver usa questa struttura per registrare le funzioni 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 operazioni file archivia informazioni specifiche del file nello spazio di contesto dell'oggetto file framework. Se il driver gestisce le operazioni dei file ma non deve archiviare le 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 non indica in precedenza che non sia necessario usare oggetti file framework.

2. Chiama la funzione di callback EvtDeviceFileCreate callback del driver, se il driver ha registrato la funzione di callback.

La funzione di callback EvtDeviceFileCreate ottiene in genere 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.

Anziché 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 (WdfRequestTypeCreate request type). Il driver riceverà successivamente richieste di creazione di file nel gestore delle richieste EvtIoDefault della coda. Una coda di I/O non può ricevere richieste di creazione file se il membro DefaultQueue della struttura di 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 WdfRequestTypeCreate-typed I/O, il framework:

• Completa tutte le richieste di creazione di file per il driver con un valore di stato di 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 cui NT_SUCCESS(stato) è uguale a FALSE. In caso contrario, un'applicazione dannosa potrebbe tentare di accedere a un dispositivo usando il nome dell'oggetto dispositivo fisico del dispositivo (PDO). (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 I/O. In caso contrario, i driver inferiori non verranno notificati che la richiesta di creazione non è riuscita e potrebbe tentare di operare come se il file sia aperto.

Se un driver inoltra una richiesta di creazione a una destinazione di I/O, il driver non può impostare il flag di 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 imposta anche il flag WdfFileObjectNotRequired come 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. Il driver può invece usare qualsiasi altra opzione di invio, ad esempio inviare in modo asincrono 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 . 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, è possibile annullare le richieste di creazione di file. 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 un oggetto file WDM non è presente. 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 sul 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 del driver a un dispositivo:

WdfFileObjectGetFileName
Restituisce il nome del 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 se le code di I/O, il driver può chiamare WdfRequestGetFileObject per ottenere un handle all'oggetto file 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 una coda di I/O per le richieste associate a un file specifico chiamando WdfIoQueueRetrieveRequestByFileObject.

Se il driver ha un puntatore a una struttura di DEVICE_OBJECT WDM, il driver può chiamare WdfDeviceGetFileObject per ottenere un handle all'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 framework.