estructura FILE_OBJECT (wdm.h)

El sistema usa la estructura FILE_OBJECT para representar un objeto de archivo. Para subsistemas protegidos en modo de usuario, un objeto de archivo representa una instancia abierta de un archivo, dispositivo, directorio o volumen. Para los controladores intermedios y del dispositivo, un objeto de archivo suele representar un objeto de dispositivo. Para los controladores de la pila del sistema de archivos, un objeto de archivo normalmente representa un directorio o archivo.

Un objeto de archivo es parcialmente opaco. Ciertos tipos de controladores, como los controladores del sistema de archivos y los controladores de transporte de red, usan algunos de los campos de objetos de archivo.

Sintaxis

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;

Miembros

Type

Miembro de solo lectura utilizado por el sistema para indicar que el objeto es un objeto de archivo. Si el objeto es un objeto de archivo, el valor de este miembro es 5.

Size

Miembro de solo lectura que especifica el tamaño, en bytes, del objeto de archivo. Este tamaño no incluye la extensión de objeto de archivo, si hay una presente.

DeviceObject

Puntero al objeto de dispositivo en el que se abre el archivo.

Vpb

Puntero al bloque de parámetros de volumen asociado al objeto de archivo.

Tenga en cuenta que si el miembro Vpb no es NULL, el archivo reside en un volumen montado.

FsContext

Puntero a cualquier estado opcional que mantenga un controlador sobre el objeto de archivo; en caso contrario, NULL. En el caso de los controladores del sistema de archivos, este miembro debe apuntar a una estructura de encabezado FSRTL_ADVANCED_FCB_HEADER contenida en una estructura específica del sistema de archivos; de lo contrario, la inestabilidad del sistema puede resultar. Normalmente, esta estructura de encabezado se inserta en un bloque de control de archivos (FCB). Sin embargo, en algunos sistemas de archivos que admiten varios flujos de datos, como NTFS, esta estructura de encabezado es un bloque de control de flujo (SCB).

En una pila de dispositivos WDM, solo el objeto de dispositivo funcional (FDO) puede usar los dos punteros de contexto. Los controladores del sistema de archivos comparten este miembro en varios se abre en el mismo flujo de datos.

FsContext2

Puntero a cualquier estado adicional que mantenga un controlador sobre el objeto de archivo; en caso contrario, NULL.

Este miembro es opaco para los controladores de la pila del sistema de archivos porque el sistema de archivos subyacente utiliza este miembro.

SectionObjectPointer

Puntero al objeto de sección de solo lectura del objeto de archivo. Este miembro solo lo establecen los sistemas de archivos y se usan para la interacción del Administrador de caché.

PrivateCacheMap

Un miembro opaco, establecido solo por sistemas de archivos, que apunta a controlar información específica y que se usa para la interacción del Administrador de caché.

FinalStatus

Miembro de solo lectura que se usa, en determinados casos sincrónicos, para indicar el estado final de la solicitud de E/S del objeto de archivo.

RelatedFileObject

Puntero a una estructura de FILE_OBJECT utilizada para indicar que el objeto de archivo actual se ha abierto en relación con un objeto de archivo ya abierto. El objeto de archivo al que apunta este miembro suele ser un directorio (lo que significa que el archivo actual se ha abierto en relación con este directorio). Sin embargo, se puede volver a abrir un archivo con respecto a sí mismo y se pueden abrir flujos de datos alternativos para un archivo en relación con un flujo de datos principal ya abierto para ese mismo archivo. El miembro RelatedFileObject solo es válido durante el procesamiento de las solicitudes de IRP_MJ_CREATE .

LockOperation

Miembro de solo lectura. Si es FALSE, nunca se ha realizado una operación de bloqueo (NtLockFile) en el objeto de archivo. Si es TRUE, se ha realizado al menos una operación de bloqueo en el objeto de archivo. Una vez establecido en TRUE, este miembro siempre sigue siendo TRUE (por ejemplo, liberar bloqueos de archivo en el objeto de archivo no restablece este miembro a FALSE).

DeletePending

Miembro de solo lectura. Si es TRUE, existe una operación de eliminación para el archivo asociado al objeto de archivo. Si es FALSE, actualmente no hay ninguna operación de eliminación pendiente para el objeto de archivo.

ReadAccess

Miembro de solo lectura. Si es TRUE, se ha abierto el archivo asociado al objeto de archivo para el acceso de lectura. Si es FALSE, el archivo se ha abierto sin acceso de lectura. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

WriteAccess

Miembro de solo lectura. Si es TRUE, el archivo asociado al objeto de archivo se ha abierto para el acceso de escritura. Si es FALSE, el archivo se ha abierto sin acceso de escritura. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

DeleteAccess

Miembro de solo lectura. Si es TRUE, se ha abierto el archivo asociado al objeto de archivo para eliminar el acceso. Si es FALSE, el archivo se ha abierto sin acceso de eliminación. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

SharedRead

Miembro de solo lectura. Si es TRUE, el archivo asociado al objeto de archivo se ha abierto para el acceso de uso compartido de lectura. Si es FALSE, el archivo se ha abierto sin acceso de uso compartido de lectura. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

SharedWrite

Miembro de solo lectura. Si es TRUE, se ha abierto el archivo asociado al objeto de archivo para el acceso compartido de escritura. Si es FALSE, el archivo se ha abierto sin acceso de uso compartido de escritura. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

SharedDelete

Miembro de solo lectura. Si es TRUE, se ha abierto el archivo asociado al objeto de archivo para eliminar el acceso compartido. Si es FALSE, el archivo se ha abierto sin eliminar el acceso compartido. Esta información se usa al comprobar o establecer el acceso compartido del archivo.

Flags

Miembro de solo lectura usado por el sistema para contener uno o varios (una combinación OR inclusiva bit a bit) de los siguientes valores de marca privada.

FileName

Estructura UNICODE_STRING cuyo miembro buffer apunta a una cadena Unicode de solo lectura que contiene el nombre del archivo abierto en el volumen. Si se abre el volumen, el miembro Length de la estructura UNICODE_STRING será cero. Tenga en cuenta que el nombre de archivo de esta cadena solo es válido durante el procesamiento inicial de una solicitud de IRP_MJ_CREATE . Este nombre de archivo no debe considerarse válido después de que el sistema de archivos comience a procesar la solicitud de IRP_MJ_CREATE . El almacenamiento de la cadena a la que apunta el miembro Buffer de la estructura UNICODE_STRING se asigna en la memoria del sistema paginada. Para obtener más información sobre cómo obtener un nombre de archivo, vea FltGetFileNameInformation.

CurrentByteOffset

Miembro de solo lectura que especifica el desplazamiento del archivo, en bytes, asociado al objeto de archivo.

Waiters

Miembro de solo lectura utilizado por el sistema para contar el número de camareros pendientes en un objeto de archivo abierto para el acceso sincrónico.

Busy

Miembro de solo lectura usado por el sistema para indicar si un objeto de archivo abierto para el acceso sincrónico está ocupado actualmente.

LastLock

Puntero opaco al último bloqueo aplicado al objeto de archivo.

Lock

Miembro opaco utilizado por el sistema para contener un bloqueo de eventos de objeto de archivo. El bloqueo de eventos se usa para controlar el acceso sincrónico al objeto de archivo. Solo se aplica a los objetos de archivo que se abren para el acceso sincrónico.

Event

Miembro opaco utilizado por el sistema para contener un objeto de evento para el objeto de archivo. El objeto de evento se usa para indicar la finalización de una solicitud de E/S en el objeto de archivo si no se proporcionó ningún evento de usuario o se llamó a una API sincrónica.

CompletionContext

Puntero opaco a la información del puerto de finalización (puntero de puerto y clave) asociado al objeto de archivo, si existe.

IrpListLock

Puntero opaco a una estructura KSPIN_LOCK que actúa como bloqueo de número usado para sincronizar el acceso a la lista IRP del objeto de archivo.

IrpList

Puntero opaco al encabezado de la lista IRP asociada al objeto de archivo.

FileObjectExtension

Puntero opaco a la estructura de extensión de objeto de archivo (FOBX) del objeto de archivo. La estructura FOBX contiene varios contextos opacos usados internamente, así como los contextos de objetos por archivo disponibles a través de rutinas FsRtl Xxx.

_IOP_FILE_OBJECT_EXTENSION

Estructura _IOP_FILE_OBJECT_EXTENSION .

Comentarios

Los controladores pueden usar los miembros FsContext y FsContext2 para mantener el estado determinado por el controlador sobre un objeto de archivo abierto. Un controlador no puede usar estos miembros a menos que el objeto de archivo sea accesible en la ubicación de pila de E/S del controlador de un IRP.

Todos los miembros restantes de un objeto de archivo son opacos o de solo lectura:

• Los miembros opacos de un objeto de archivo deben considerarse inaccesibles. Es posible que los controladores con dependencias en las ubicaciones del campo de objeto o el acceso a miembros opacos no permanezcan portátiles e interoperables con otros controladores a lo largo del tiempo.

• Los controladores pueden usar miembros de solo lectura para adquirir información relevante, pero no deben modificar miembros de solo lectura y, si es un puntero, el objeto al que apunta el miembro.

Durante el procesamiento de una solicitud de IRP_MJ_CREATE , un controlador del sistema de archivos llama a la rutina IoSetShareAccess (si el cliente es el primero en abrir el archivo) o la rutina IoCheckShareAccess (para los clientes posteriores que desean compartir el archivo). Los miembros IoSetShareAccess e IoCheckShareAccess actualizan los miembros ReadAccess, WriteAccess y DeleteAccess para indicar los derechos de acceso que se conceden al cliente si el cliente tiene acceso exclusivo al archivo. Además, IoCheckShareAccess actualiza los miembros SharedRead, SharedWrite y SharedDelete para indicar los derechos de acceso que se conceden simultáneamente a dos o más clientes que comparten el archivo. Si el controlador de un dispositivo distinto de un sistema de archivos tiene que supervisar los derechos de acceso de los clientes, este controlador normalmente almacena información de derechos de acceso en búferes de contexto a los que apuntan los miembros FsContext y FsContext2 .

El tipo de objeto (por ejemplo, un archivo, directorio o volumen) que representa un objeto de archivo determinado no se puede determinar examinando únicamente el contenido de la estructura de objetos de archivo. Para obtener información sobre cómo determinar el tipo de objeto que representa un objeto de archivo, vea ZwQueryInformationFile.

El sistema de archivos de registro común (CLFS) usa la estructura LOG_FILE_OBJECT para representar los registros. La función ClfsCreateLogFile devuelve un puntero a una estructura de LOG_FILE_OBJECT , que los clientes pasan a otras funciones CLFS.

Los clientes CLFS no acceden directamente a los miembros de una estructura de LOG_FILE_OBJECT .

typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;

Requisitos

Consulte también

DEVICE_OBJECT

FOBX

FSRTL_ADVANCED_FCB_HEADER

IRP_MJ_CREATE

IoCheckShareAccess

IoGetDeviceObjectPointer

IoSetShareAccess

ObDereferenceObject

ZwQueryInformationFile