Objets de fichier framework
Lorsqu’une application ou un pilote tente d’accéder à un appareil, généralement en créant ou en ouvrant un fichier, le système d’exploitation envoie une demande de création de fichier à la pile de pilotes. Lorsque l’application ou le pilote a terminé d’utiliser l’appareil, le système envoie le nettoyage des fichiers et les demandes de fermeture à la pile des pilotes. Les types de requêtes de ces trois requêtes sont respectivement WdfRequestTypeCreate, WdfRequestTypeCleanup et WdfRequestTypeClose.
En règle générale, à moins que votre pilote n’ait appelé WdfDeviceInitSetExclusive, le pilote doit effectuer des opérations spécifiques aux fichiers ou d’autres opérations spécifiques à l’accès lorsqu’il reçoit des demandes de création, de nettoyage et de fermeture de fichier, car plusieurs fichiers peuvent être ouverts simultanément ou plusieurs applications peuvent accéder simultanément à l’appareil. Le pilote doit donc suivre les demandes d’E/S associées à chaque fichier ou application.
L’infrastructure définit des objets de fichier framework, qui représentent les moyens d’une application ou d’un pilote pour accéder à un appareil, tels qu’un fichier, un répertoire, un volume, un emplacement de messagerie, un canal nommé ou l’ensemble de l’appareil. Un nom de fichier peut être associé à un objet file, mais la signification d’un nom de fichier est spécifique au pilote. Pour plus d’informations sur les noms de fichiers, consultez Contrôle de l’accès à l’espace de noms d’appareil.
Si votre pilote doit gérer les opérations de fichier, il doit appeler WdfDeviceInitSetFileObjectConfig à partir de sa fonction de rappel EvtDriverDeviceAdd . La méthode WdfDeviceInitSetFileObjectConfig reçoit une structure WDF_FILEOBJECT_CONFIG comme entrée. Le pilote utilise cette structure pour inscrire ses fonctions de rappel EvtDeviceFileCreate, EvtFileCleanup et EvtFileClose et, éventuellement, pour indiquer si l’infrastructure doit créer un objet de fichier framework chaque fois que le pilote reçoit une demande de création de fichier.
La plupart des pilotes qui gèrent les opérations de fichiers stockent des informations spécifiques aux fichiers dans l’espace contextuel de l’objet de fichier framework. Si votre pilote gère les opérations de fichier mais n’a pas besoin de stocker des informations dans l’espace de contexte d’un objet de fichier, l’infrastructure n’a pas besoin de créer des objets de fichier framework pour le pilote.
Création ou ouverture d’un fichier
Lorsque l’infrastructure reçoit une demande de création de fichier pour votre pilote de fonction, elle :
Crée un objet de fichier framework qui représente le fichier, sauf si le pilote a indiqué précédemment qu’il n’a pas besoin d’utiliser d’objets de fichier framework.
Appelle la fonction de rappel EvtDeviceFileCreate de votre pilote, si le pilote a inscrit la fonction de rappel.
La fonction de rappel EvtDeviceFileCreate obtient généralement des informations sur le fichier, telles que son nom et ses indicateurs d’objet de fichier. Le pilote stocke généralement ces informations dans l’espace de contexte de l’objet de fichier framework.
Au lieu de fournir une fonction de rappel EvtDeviceFileCreate , le pilote peut appeler WdfDeviceConfigureRequestDispatching pour définir une file d’attente d’E/S pour recevoir toutes les demandes de création de fichiers (type de requête WdfRequestTypeCreate ). Le pilote recevra ensuite les demandes de création de fichiers dans le gestionnaire de requêtes EvtIoDefault de la file d’attente. (Une file d’attente d’E/S ne peut pas recevoir de demandes de création de fichier si le membre DefaultQueue de la structure WDF_IO_QUEUE_CONFIG de la file d’attente a la valeur TRUE.)
Si votre pilote ne fournit pas de fonction de rappel EvtDeviceFileCreate et ne configure pas une file d’attente d’E/S pour gérer les demandes d’E/S de type WdfRequestTypeCreate, l’infrastructure :
Exécute toutes les demandes de création de fichiers pour le pilote avec une valeur status de STATUS_SUCCESS, si votre pilote est un pilote de fonction.
Transfère toutes les demandes de création de fichiers au pilote inférieur suivant, si votre pilote est un pilote de filtre.
(Pour voir comment modifier ce comportement, consultez le membre AutoForwardCleanupClose de la structure WDF_FILEOBJECT_CONFIG .)
Note Si votre pilote de fonction ne fournit pas d’interfaces d’appareil que les applications peuvent utiliser pour accéder aux périphériques du pilote, le pilote doit fournir une fonction de rappel EvtDeviceFileCreate qui termine toutes les demandes de création de fichiers avec une valeur status pour laquelle NT_SUCCESS(status) est égal à FALSE. Sinon, une application malveillante peut tenter d’accéder à un appareil en utilisant le nom de l’objet d’appareil physique (PDO) de l’appareil. (Tous les PDO ont des noms.)
Si un pilote transfère une demande de création à une cible d’E/S, le pilote ne doit pas effectuer la requête avec une valeur d’échec status, sauf si le pilote reçoit une valeur d’échec status de la cible d’E/S. Sinon, les pilotes inférieurs ne sont pas avertis que la demande de création a échoué et peuvent tenter de fonctionner comme si le fichier était ouvert.
Si un pilote transfère une demande de création à une cible d’E/S, le pilote ne peut pas définir l’indicateur WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET si l’infrastructure a créé un objet de fichier framework pour la demande de création. Par conséquent, le pilote ne peut pas définir l’indicateur WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET pour une demande de création, sauf s’il définit également l’indicateur WdfFileObjectNotRequired, car le pilote ne pourra pas propre l’objet WDFFILEOBJECT dans le cas où un pilote inférieur dans la pile échoue à la demande de création. Au lieu de cela, le pilote peut utiliser n’importe quelle autre option d’envoi, par exemple envoyer de manière asynchrone avec une routine d’achèvement ou envoyer de manière synchrone. Dans les deux cas, le pilote doit appeler WdfRequestComplete lorsqu’il reprend le contrôle.
Notez que si un pilote termine une demande de création avec une erreur status, l’infrastructure supprime l’objet de fichier framework, mais n’appelle pas les fonctions de rappel EvtFileCleanup ou EvtFileClose du pilote. Par conséquent, si le pilote alloue une mémoire supplémentaire spécifique à l’objet en dehors de l’espace contextuel de l’objet fichier, il doit fournir une fonction de rappel EvtCleanupCallback ou EvtDestroyCallback qui supprime la mémoire allouée.
Pour Windows Vista et versions ultérieures, les demandes de création de fichiers peuvent être annulées. Les versions antérieures du système d’exploitation Windows ne prennent pas en charge l’annulation des demandes de création de fichiers.
Le système crée toujours un objet de fichier WDM (Windows Driver Model) pour chaque demande de création provenant d’une application utilisateur. Si un pilote envoie une demande de création, il se peut qu’il ne crée pas d’objet de fichier WDM pour la demande. En règle générale, l’infrastructure ne crée pas d’objet de fichier framework si un objet de fichier WDM n’est pas présent. Toutefois, si votre pilote a appelé WdfDeviceInitSetExclusive et si le pilote a défini WdfFileObjectWdfCannotUseFsContexts dans le membre FileObjectClass de la structure WDF_FILEOBJECT_CONFIG , l’infrastructure crée un objet de fichier d’infrastructure même si un objet de fichier WDM n’existe pas.
Obtention d’informations de fichier
La fonction de rappel EvtDeviceFileCreate du pilote peut appeler une ou plusieurs des méthodes d’objet suivantes pour obtenir des informations sur l’accès d’une application ou du pilote à un appareil :
WdfFileObjectGetFileName
Retourne le nom de fichier contenu dans un objet de fichier framework.
WdfFileObjectGetFlags
Retourne les indicateurs contenus dans un objet de fichier framework.
WdfFileObjectWdmGetFileObject
Renvoie l’objet de fichier WDM associé à un objet de fichier framework.
WdfRequestGetParameters
Récupère les paramètres associés à un objet de demande d’infrastructure. Si le type de requête est WdfRequestTypeCreate, le membre Parameters.Create de la structure WDF_REQUEST_PARAMETERS contient des informations sur la demande de création de fichier.
En règle générale, le pilote stocke les informations de fichier dans l’espace de contexte de l’objet de fichier framework. Lorsque votre pilote obtient une requête d’E/S d’une requête si ses files d’attente d’E/S sont présentes, le pilote peut appeler WdfRequestGetFileObject pour obtenir un handle pour l’objet de fichier framework associé à la demande. Le pilote peut ensuite récupérer les informations de fichier qu’il a stockées dans l’espace de contexte de l’objet de fichier framework.
Votre pilote peut rechercher des requêtes associées à un fichier particulier dans une file d’attente d’E/S en appelant WdfIoQueueRetrieveRequestByFileObject.
Si votre pilote a un pointeur vers une structure de DEVICE_OBJECT WDM, celui-ci peut appeler WdfDeviceGetFileObject pour obtenir un handle vers l’objet de fichier framework associé à l’objet de périphérique WDM.
Fermeture d’un fichier
Lorsqu’une application ou un autre pilote ferme un fichier, l’infrastructure reçoit une demande de nettoyage et une demande de fermeture pour votre pilote. L’infrastructure :
Appelle les fonctions de rappel EvtFileCleanup et EvtFileClose de votre pilote, si le pilote a inscrit ces fonctions de rappel.
Supprime l’objet de fichier framework qui représente le fichier.
Les fonctions de rappel EvtFileCleanup et EvtFileClose du pilote reçoivent un handle pour l’objet de fichier framework. Le pilote peut appeler WdfFileObjectGetDevice pour déterminer quel objet d’appareil framework est associé à l’objet de fichier framework.