structure FILE_OBJECT (wdm.h)
La structure FILE_OBJECT est utilisée par le système pour représenter un objet de fichier. Pour les sous-systèmes protégés en mode utilisateur, un objet de fichier représente une instance ouverte d’un fichier, d’un appareil, d’un répertoire ou d’un volume. Pour les pilotes périphériques et intermédiaires, un objet de fichier représente généralement un objet d’appareil. Pour les pilotes de la pile du système de fichiers, un objet de fichier représente généralement un répertoire ou un fichier.
Un objet de fichier est partiellement opaque. Certains types de pilotes, tels que les pilotes de système de fichiers et les pilotes de transport réseau, utilisent certains des champs d’objets de fichier.
Syntaxe
typedef struct _FILE_OBJECT {
CSHORT Type;
CSHORT Size;
PDEVICE_OBJECT DeviceObject;
PVPB Vpb;
PVOID FsContext;
PVOID FsContext2;
PSECTION_OBJECT_POINTERS SectionObjectPointer;
PVOID PrivateCacheMap;
NTSTATUS FinalStatus;
struct _FILE_OBJECT *RelatedFileObject;
BOOLEAN LockOperation;
BOOLEAN DeletePending;
BOOLEAN ReadAccess;
BOOLEAN WriteAccess;
BOOLEAN DeleteAccess;
BOOLEAN SharedRead;
BOOLEAN SharedWrite;
BOOLEAN SharedDelete;
ULONG Flags;
UNICODE_STRING FileName;
LARGE_INTEGER CurrentByteOffset;
__volatile ULONG Waiters;
__volatile ULONG Busy;
PVOID LastLock;
KEVENT Lock;
KEVENT Event;
__volatile PIO_COMPLETION_CONTEXT CompletionContext;
KSPIN_LOCK IrpListLock;
LIST_ENTRY IrpList;
__volatile _IOP_FILE_OBJECT_EXTENSION *FileObjectExtension;
struct _IOP_FILE_OBJECT_EXTENSION;
} FILE_OBJECT, *PFILE_OBJECT;
Membres
Type
Membre en lecture seule utilisé par le système pour indiquer que l’objet est un objet de fichier. Si l’objet est un objet de fichier, la valeur de ce membre est 5.
Size
Membre en lecture seule qui spécifie la taille, en octets, de l’objet fichier. Cette taille n’inclut pas l’extension d’objet de fichier, si elle est présente.
DeviceObject
Pointeur vers l’objet d’appareil sur lequel le fichier est ouvert.
Vpb
Pointeur vers le bloc de paramètres de volume associé à l’objet fichier.
Notez que si le membre Vpb n’est pasNULL, le fichier réside sur un volume monté.
FsContext
Pointeur vers l’état facultatif qu’un pilote conserve sur l’objet de fichier ; sinon, NULL . Pour les pilotes de système de fichiers, ce membre doit pointer vers une structure d’en-tête FSRTL_ADVANCED_FCB_HEADER contenue dans une structure spécifique au système de fichiers ; sinon, l’instabilité du système peut se produire. En règle générale, cette structure d’en-tête est incorporée dans un bloc de contrôle de fichier (FCB). Toutefois, sur certains systèmes de fichiers qui prennent en charge plusieurs flux de données, tels que NTFS, cette structure d’en-tête est un bloc de contrôle de flux (SCB).
Dans une pile d’appareils WDM, seul l’objet d’appareil fonctionnel (FDO) peut utiliser les deux pointeurs de contexte. Les pilotes de système de fichiers partagent ce membre sur plusieurs ouvertures vers le même flux de données.
FsContext2
Pointeur vers un état supplémentaire qu’un pilote conserve sur l’objet de fichier ; sinon, NULL .
Ce membre est opaque pour les pilotes dans la pile du système de fichiers, car le système de fichiers sous-jacent utilise ce membre.
SectionObjectPointer
Pointeur vers l’objet de section en lecture seule de l’objet de fichier. Ce membre est défini uniquement par les systèmes de fichiers et utilisé pour l’interaction du Gestionnaire de cache.
PrivateCacheMap
Membre opaque, défini uniquement par les systèmes de fichiers, qui pointe vers des informations spécifiques et qui est utilisé pour l’interaction du Gestionnaire de cache.
FinalStatus
Membre en lecture seule utilisé, dans certains cas synchrones, pour indiquer l’état final de la demande d’E/S de l’objet fichier.
RelatedFileObject
Pointeur vers une structure de FILE_OBJECT utilisée pour indiquer que l’objet de fichier actuel a été ouvert par rapport à un objet de fichier déjà ouvert. L’objet de fichier vers lequel pointe ce membre est généralement un répertoire (ce qui signifie que le fichier actuel a été ouvert par rapport à ce répertoire). Toutefois, un fichier peut être rouvert par rapport à lui-même, et d’autres flux de données pour un fichier peuvent être ouverts par rapport à un flux de données principal déjà ouvert pour ce même fichier. Le membre RelatedFileObject n’est valide que pendant le traitement des demandes de IRP_MJ_CREATE.
LockOperation
Membre en lecture seule. Si FALSE, une opération de verrouillage (NtLockFile) n’a jamais été effectuée sur l’objet de fichier. Si TRUE, au moins une opération de verrouillage a été effectuée sur l’objet de fichier. Une fois défini sur TRUE, ce membre reste toujours TRUE (par exemple, la libération de verrous de fichier sur l’objet de fichier ne réinitialise pas ce membre pour FALSE).
DeletePending
Membre en lecture seule. Si TRUE, une opération de suppression pour le fichier associé à l’objet de fichier existe. Si FALSE, il n’existe actuellement aucune opération de suppression en attente pour l’objet fichier.
ReadAccess
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour l’accès en lecture. Si FAUX, le fichier a été ouvert sans accès en lecture. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
WriteAccess
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour l’accès en écriture. Si FALSE, le fichier a été ouvert sans accès en écriture. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
DeleteAccess
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour l’accès de suppression. Si FAUX, le fichier a été ouvert sans supprimer l’accès. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
SharedRead
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour l’accès au partage de lecture. Si FAUX, le fichier a été ouvert sans accès en lecture. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
SharedWrite
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour l’accès au partage d’écriture. Si FALSE, le fichier a été ouvert sans accès au partage d’écriture. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
SharedDelete
Membre en lecture seule. Si TRUE, le fichier associé à l’objet de fichier a été ouvert pour supprimer l’accès au partage. Si FAUX, le fichier a été ouvert sans supprimer l’accès au partage. Ces informations sont utilisées lors de la vérification et/ou de la définition de l’accès au partage du fichier.
Flags
Membre en lecture seule utilisé par le système pour contenir une ou plusieurs (combinaison OR inclusive au niveau du bit) des valeurs d’indicateur privé suivantes.
| Drapeau | Signification |
|---|---|
| FO_FILE_OPEN | Obsolescent. |
| FO_SYNCHRONOUS_IO | L’objet fichier est ouvert pour les E/S synchrones. |
| FO_ALERTABLE_IO | Toute attente dans le gestionnaire d’E/S, à la suite d’une demande adressée à cet objet de fichier, est alertable. |
| FO_NO_INTERMEDIATE_BUFFERING | Le fichier associé à l’objet de fichier ne peut pas être mis en cache ou mis en mémoire tampon dans les mémoires tampons internes d’un pilote. |
| FO_WRITE_THROUGH | Les services système, les pilotes de système de fichiers et les pilotes qui écrivent des données dans le fichier doivent transférer les données dans le fichier avant toute opération d’écriture demandée est considérée comme terminée. |
| FO_SEQUENTIAL_ONLY | Le fichier associé à l’objet de fichier a été ouvert uniquement pour les opérations d’E/S séquentielles. |
| FO_CACHE_SUPPORTED | Le fichier associé à l’objet de fichier est mis en cache. Cet indicateur doit être défini uniquement par un pilote de système de fichiers et uniquement si le membre FsContext pointe vers une structure de FSRTL_ADVANCED_FCB_HEADER valide. |
| FO_NAMED_PIPE | L’objet fichier représente un canal nommé. |
| FO_STREAM_FILE | L’objet fichier représente un flux de fichiers. |
| FO_MAILSLOT | L’objet fichier représente un maillot. |
| FO_GENERATE_AUDIT_ON_CLOSE | Obsolescent. |
| FO_QUEUE_IRP_TO_THREAD | Les irps ne sont pas mis en file d’attente vers cet objet de fichier. |
| FO_DIRECT_DEVICE_OPEN | L’appareil ciblé par cet objet de fichier a été ouvert directement. |
| FO_FILE_MODIFIED | Le fichier associé à l’objet de fichier a été modifié. |
| FO_FILE_SIZE_CHANGED | Le fichier associé à l’objet de fichier a changé de taille. |
| FO_CLEANUP_COMPLETE | Le système de fichiers a terminé son nettoyage pour cet objet de fichier. |
| FO_TEMPORARY_FILE | Le fichier associé à l’objet fichier est un fichier temporaire. |
| FO_DELETE_ON_CLOSE | Le fichier associé à l’objet de fichier est supprimé par le système de fichiers à la fermeture. |
| FO_OPENED_CASE_SENSITIVE | Le cas de nom de fichier du fichier associé à l’objet de fichier est respecté. |
| FO_HANDLE_CREATED | Un handle de fichier a été créé pour l’objet de fichier. |
| FO_FILE_FAST_IO_READ | Une lecture rapide d’E/S a été effectuée sur cet objet de fichier. |
| FO_RANDOM_ACCESS | Le fichier associé à l’objet de fichier a été ouvert pour l’accès aléatoire. |
| FO_FILE_OPEN_CANCELLED | La demande de création de cet objet de fichier a été annulée avant la fin. |
| FO_VOLUME_OPEN | L’objet fichier représente une demande d’ouverture de volume. |
| FO_REMOTE_ORIGIN | La demande de création du fichier associé à l’objet de fichier provient d’un ordinateur distant. |
| FO_SKIP_COMPLETION_PORT | Pour un objet de fichier associé à un port, détermine si le système doit ignorer la file d’attente vers le port d’achèvement lorsque l’IRP est terminé de façon synchrone avec une valeur de retour d’état non-erreur. |
| FO_SKIP_SET_EVENT | Ignorez la définition de l’événement pour l’objet de fichier à la fin de l’IRP. |
| FO_SKIP_SET_FAST_IO | Ignorez la définition d’un événement fourni à un service système lorsque le chemin d’E/S rapide réussit. |
FileName
Structure UNICODE_STRING dont membre buffer pointe vers une chaîne Unicode en lecture seule qui contient le nom du fichier ouvert sur le volume. Si le volume est ouvert, le membre Length de la structure UNICODE_STRING est égal à zéro. Notez que le nom de fichier de cette chaîne est valide uniquement pendant le traitement initial d’une demande de IRP_MJ_CREATE. Ce nom de fichier ne doit pas être considéré comme valide une fois que le système de fichiers commence à traiter la demande de IRP_MJ_CREATE. Le stockage de la chaîne pointée par le de la mémoire tampon membre de la structure UNICODE_STRING est alloué dans la mémoire système paginée. Pour plus d’informations sur l’obtention d’un nom de fichier, consultez FltGetFileNameInformation.
CurrentByteOffset
Membre en lecture seule qui spécifie le décalage de fichier, en octets, associé à l’objet de fichier.
Waiters
Membre en lecture seule utilisé par le système pour compter le nombre de serveurs en attente sur un objet de fichier ouvert pour l’accès synchrone.
Busy
Membre en lecture seule utilisé par le système pour indiquer si un objet de fichier ouvert pour l’accès synchrone est actuellement occupé.
LastLock
Pointeur opaque vers le dernier verrou appliqué à l’objet fichier.
Lock
Membre opaque utilisé par le système pour contenir un verrou d’événement d’objet de fichier. Le verrou d’événement est utilisé pour contrôler l’accès synchrone à l’objet de fichier. Applicable uniquement aux objets de fichier ouverts pour l’accès synchrone.
Event
Membre opaque utilisé par le système pour contenir un objet d’événement pour l’objet fichier. L’objet d’événement est utilisé pour signaler l’achèvement d’une requête d’E/S sur l’objet fichier si aucun événement utilisateur n’a été fourni ou qu’une API synchrone a été appelée.
CompletionContext
Pointeur opaque vers les informations de port d’achèvement (pointeur de port et clé) associées à l’objet de fichier, le cas échéant.
IrpListLock
Pointeur opaque vers une structure KSPIN_LOCK qui sert de verrou de rotation utilisé pour synchroniser l’accès à la liste IRP de l’objet de fichier.
IrpList
Pointeur opaque vers la tête de la liste IRP associée à l’objet fichier.
FileObjectExtension
Pointeur opaque vers l’extension d’objet de fichier de l’objet fichier (structure FOBX). La structure FOBX contient différents contextes opaques utilisés en interne, ainsi que les contextes d’objet par fichier disponibles via routines deXxx.
_IOP_FILE_OBJECT_EXTENSION
Structure _IOP_FILE_OBJECT_EXTENSION.
Remarques
Les pilotes peuvent utiliser les membres FsContext et FsContext2 pour maintenir l’état déterminé par le pilote sur un objet de fichier ouvert. Un pilote ne peut pas utiliser ces membres, sauf si l’objet de fichier est accessible à l’emplacement de la pile d’E/S du pilote d’un IRP.
Tous les membres restants d’un objet de fichier sont opaques ou en lecture seule :
Les membres opaques au sein d’un objet de fichier doivent être considérés comme inaccessibles. Les pilotes ayant des dépendances sur les emplacements de champ d’objet ou l’accès aux membres opaques peuvent ne pas rester portables et interopérables avec d’autres pilotes au fil du temps.
Les pilotes peuvent utiliser des membres en lecture seule pour acquérir des informations pertinentes, mais ne doivent pas modifier les membres en lecture seule et, si un pointeur, l’objet vers lequel le membre pointe.
Pendant le traitement d’une demande de IRP_MJ_CREATE, un pilote de système de fichiers appelle la routine IoSetShareAccess (si le client est le premier à ouvrir le fichier) ou la routine IoCheckShareAccess (pour les clients suivants qui souhaitent partager le fichier). IoSetShareAccess et IoCheckShareAccess mettre à jour les ReadAccess, WriteAccesset membres DeleteAccess pour indiquer les droits d’accès accordés au client si le client a un accès exclusif au fichier. En outre, IoCheckShareAccess met à jour les SharedRead, SharedWriteet membres de SharedDelete pour indiquer les droits d’accès accordés simultanément à deux clients qui partagent le fichier. Si le pilote d’un périphérique autre qu’un système de fichiers doit surveiller les droits d’accès des clients, ce pilote stocke généralement les informations de droits d’accès dans des mémoires tampons contextuelles pointées par le FsContext et membres FsContext2.
Le type d’objet (par exemple, un fichier, un répertoire ou un volume) qu’un objet de fichier donné représente ne peut pas être déterminé en examinant uniquement le contenu de la structure d’objet de fichier. Pour plus d’informations sur la façon de déterminer le type d’objet qu’un objet de fichier représente, consultez ZwQueryInformationFile.
Common Log File System (CLFS) utilise la structure LOG_FILE_OBJECT pour représenter les journaux. La fonction ClfsCreateLogFile retourne un pointeur vers une structure LOG_FILE_OBJECT, que les clients passent ensuite à d’autres fonctions CLFS.
Les clients CLFS n’accèdent pas directement aux membres d’une structure LOG_FILE_OBJECT.
typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;
Exigences
| Exigence | Valeur |
|---|---|
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |