Partager via


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)

Voir aussi

DEVICE_OBJECT

FOBX

FSRTL_ADVANCED_FCB_HEADER

IRP_MJ_CREATE

IoCheckShareAccess

IoGetDeviceObjectPointer

IoSetShareAccess

ObDereferenceObject

ZwQueryInformationFile