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 fichier représente un instance ouvert d’un fichier, d’un appareil, d’un répertoire ou d’un volume. Pour les pilotes d’appareil et intermédiaires, un objet fichier représente généralement un objet d’appareil. Pour les pilotes de la pile du système de fichiers, un objet file représente généralement un répertoire ou un fichier.
Un objet file 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 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 file, 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, le cas échéant.
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’a pas la valeur NULL, le fichier réside sur un volume monté.
FsContext
Pointeur vers l’état facultatif qu’un pilote maintient à propos de 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 en résulter. 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 entre plusieurs ouvertures sur le même flux de données.
FsContext2
Pointeur vers l’état supplémentaire qu’un pilote maintient à propos de l’objet de fichier ; sinon, NULL.
Ce membre est opaque pour les pilotes de 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 fichier. Ce membre est défini uniquement par les systèmes de fichiers et utilisé pour l’interaction avec Cache Manager.
PrivateCacheMap
Membre opaque, défini uniquement par les systèmes de fichiers, qui pointe vers des informations spécifiques à la gestion et qui est utilisé pour l’interaction du Gestionnaire de cache.
FinalStatus
Membre en lecture seule utilisé, dans certains cas synchrones, pour indiquer la status finale de la demande d’E/S de l’objet fichier.
RelatedFileObject
Pointeur vers une structure FILE_OBJECT utilisée pour indiquer que l’objet fichier actif a été ouvert par rapport à un objet fichier déjà ouvert. L’objet de fichier pointé par ce membre est généralement un répertoire (ce qui signifie que le fichier actif 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 d’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 la valeur est FALSE, une opération de verrouillage (NtLockFile) n’a jamais été effectuée sur l’objet de fichier. Si la valeur est TRUE, au moins une opération de verrouillage a été effectuée sur l’objet fichier. Une fois défini sur TRUE, ce membre reste toujours TRUE (par exemple, la libération des verrous de fichier sur l’objet fichier ne réinitialise pas ce membre à FALSE).
DeletePending
Membre en lecture seule. Si la valeur EST TRUE, une opération de suppression du fichier associé à l’objet fichier existe. Si la valeur est FALSE, il n’y a actuellement aucune opération de suppression en attente pour l’objet fichier.
ReadAccess
Membre en lecture seule. Si la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour l’accès en lecture. Si la valeur est FALSE, 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 la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour l’accès en écriture. Si la valeur est 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 la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour l’accès de suppression. Si la valeur est FALSE, le fichier a été ouvert sans accès de suppression. 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 la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour l’accès en partage en lecture. Si la valeur est FALSE, le fichier a été ouvert sans accès de partage de 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 la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour l’accès au partage d’écriture. Si la valeur est FALSE, le fichier a été ouvert sans accès de partage 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.
SharedDelete
Membre en lecture seule. Si la valeur est TRUE, le fichier associé à l’objet file a été ouvert pour supprimer l’accès de partage. Si la valeur est FALSE, le fichier a été ouvert sans supprimer l’accès de 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.
| Indicateur | Signification |
|---|---|
| FO_FILE_OPEN | Action déconseillée. |
| FO_SYNCHRONOUS_IO | L’objet file 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 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 que toute opération d’écriture demandée soit considérée comme terminée. |
| FO_SEQUENTIAL_ONLY | Le fichier associé à l’objet file a été ouvert uniquement pour les opérations d’E/S séquentielles. |
| FO_CACHE_SUPPORTED | Le fichier associé à l’objet file 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 FSRTL_ADVANCED_FCB_HEADER valide. |
| FO_NAMED_PIPE | L’objet file représente un canal nommé. |
| FO_STREAM_FILE | L’objet file représente un flux de fichiers. |
| FO_MAILSLOT | L’objet file représente un maillot. |
| FO_GENERATE_AUDIT_ON_CLOSE | Action déconseillée. |
| FO_QUEUE_IRP_TO_THREAD | Les IIP ne seront 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 file a été modifié. |
| FO_FILE_SIZE_CHANGED | La taille du fichier associée à l’objet file a changé. |
| 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 file est un fichier temporaire. |
| FO_DELETE_ON_CLOSE | Le fichier associé à l’objet file sera supprimé par le système de fichiers à la fermeture. |
| FO_OPENED_CASE_SENSITIVE | La casse du nom de fichier du fichier associé à l’objet file est respectée. |
| FO_HANDLE_CREATED | Un handle de fichier a été créé pour l’objet fichier. |
| FO_FILE_FAST_IO_READ | Une lecture d’E/S rapide a été effectuée sur cet objet de fichier. |
| FO_RANDOM_ACCESS | Le fichier associé à l’objet file a été ouvert pour un accès aléatoire. |
| FO_FILE_OPEN_CANCELLED | La demande de création de cet objet de fichier a été annulée avant de se terminer. |
| FO_VOLUME_OPEN | L’objet file représente une demande d’ouverture de volume. |
| FO_REMOTE_ORIGIN | La demande de création du fichier associé à l’objet file provient d’un ordinateur distant. |
| FO_SKIP_COMPLETION_PORT | Pour un objet fichier associé à un port, détermine si le système doit ignorer la mise en file d’attente vers le port d’achèvement lorsque l’IRP est terminé de façon synchrone avec une valeur de retour status sans erreur. |
| FO_SKIP_SET_EVENT | Ignorez la définition de l’événement pour l’objet fichier à l’achèvement 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 le membre Buffer pointe vers une chaîne Unicode en lecture seule contenant 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 dans 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 a commencé à traiter la demande de IRP_MJ_CREATE . Le stockage de la chaîne pointée par le membre Buffer 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 file.
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 un accès synchrone.
Busy
Membre en lecture seule utilisé par le système pour indiquer si un objet fichier ouvert pour un 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 fichier. Le verrou d’événement est utilisé pour contrôler l’accès synchrone à l’objet fichier. Applicable uniquement aux objets fichier ouverts pour un accès synchrone.
Event
Membre opaque utilisé par le système pour contenir un objet d’événement pour l’objet file. L’objet event est utilisé pour signaler l’achèvement d’une demande d’E/S sur l’objet fichier si aucun événement utilisateur n’a été fourni ou si 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 fichier, le cas échéant.
IrpListLock
Pointeur opaque vers une structure de KSPIN_LOCK qui sert de verrou de rotation utilisé pour synchroniser l’accès à la liste IRP de l’objet fichier.
IrpList
Pointeur opaque vers le début de la liste IRP associée à l’objet fichier.
FileObjectExtension
Pointeur opaque vers la structure FOBX (File Object Extension) de l’objet file. La structure FOBX contient différents contextes opaques utilisés en interne, ainsi que les contextes d’objet par fichier disponibles via les routines FsRtlXxx .
_IOP_FILE_OBJECT_EXTENSION
Structure _IOP_FILE_OBJECT_EXTENSION .
Remarques
Les pilotes peuvent utiliser les membres FsContext et FsContext2 pour conserver l’état déterminé par le pilote à propos d’un objet de fichier ouvert. Un pilote ne peut pas utiliser ces membres, sauf si l’objet file est accessible dans l’emplacement de la pile d’E/S du pilote d’un IRP.
Tous les membres restants d’un objet fichier sont opaques ou en lecture seule :
Les membres opaques au sein d’un objet 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 ni, 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 mettent à jour les membres ReadAccess, WriteAccess et DeleteAccess pour indiquer les droits d’accès accordés au client si le client dispose d’un accès exclusif au fichier. En outre, IoCheckShareAccess met à jour les membres SharedRead, SharedWrite et SharedDelete pour indiquer les droits d’accès accordés simultanément à deux ou plusieurs clients qui partagent le fichier. Si le pilote d’un appareil 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 les mémoires tampons de contexte pointées par les membres FsContext et 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 de l’objet fichier. Pour plus d’informations sur la façon de déterminer le type d’objet qu’un objet file représente, consultez ZwQueryInformationFile.
Le 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;
Configuration requise
| Condition requise | Valeur |
|---|---|
| En-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |