Compartilhar via


estrutura FILE_OBJECT (wdm.h)

A estrutura FILE_OBJECT é usada pelo sistema para representar um objeto de arquivo. Para subsistemas protegidos no modo de usuário, um objeto de arquivo representa uma instância aberta de um arquivo, dispositivo, diretório ou volume. Para drivers intermediários e de dispositivo, um objeto de arquivo geralmente representa um objeto de dispositivo. Para drivers na pilha do sistema de arquivos, um objeto de arquivo geralmente representa um diretório ou arquivo.

Um objeto de arquivo é parcialmente opaco. Determinados tipos de drivers, como drivers do sistema de arquivos e drivers de transporte de rede, usam alguns dos campos de objetos de arquivo.

Sintaxe

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;

Membros

Type

Um membro somente leitura usado pelo sistema para indicar que o objeto é um objeto de arquivo. Se o objeto for um objeto de arquivo, o valor desse membro será 5.

Size

Um membro somente leitura que especifica o tamanho, em bytes, do objeto de arquivo. Esse tamanho não inclui a extensão de objeto de arquivo, se houver uma.

DeviceObject

Um ponteiro para o objeto do dispositivo no qual o arquivo é aberto.

Vpb

Um ponteiro para o bloco de parâmetros de volume associado ao objeto de arquivo.

Observe que, se o membro Vpb não for NULL, o arquivo residirá em um volume montado.

FsContext

Um ponteiro para qualquer estado opcional que um driver mantém sobre o objeto de arquivo; caso contrário, NULL. Para drivers do sistema de arquivos, esse membro deve apontar para uma estrutura de cabeçalho FSRTL_ADVANCED_FCB_HEADER contida em uma estrutura específica do sistema de arquivos; caso contrário, a instabilidade do sistema pode resultar. Normalmente, essa estrutura de cabeçalho é inserida em um FCB (bloco de controle de arquivo). No entanto, em alguns sistemas de arquivos que dão suporte a vários fluxos de dados, como o NTFS, essa estrutura de cabeçalho é um SCB (bloco de controle de fluxo).

Em uma pilha de dispositivos WDM, somente o FDO (objeto de dispositivo funcional) pode usar os dois ponteiros de contexto. Os drivers do sistema de arquivos compartilham esse membro em várias aberturas para o mesmo fluxo de dados.

FsContext2

Um ponteiro para qualquer estado adicional que um driver mantém sobre o objeto de arquivo; caso contrário, NULL.

Esse membro é opaco para drivers na pilha do sistema de arquivos porque o sistema de arquivos subjacente utiliza esse membro.

SectionObjectPointer

Um ponteiro para o objeto de seção somente leitura do objeto de arquivo. Esse membro é definido apenas por sistemas de arquivos e usado para interação do Gerenciador de Cache.

PrivateCacheMap

Um membro opaco, definido apenas por sistemas de arquivos, que aponta para manipular informações específicas e que são usadas para interação do Gerenciador de Cache.

FinalStatus

Um membro somente leitura usado, em determinados casos síncronos, para indicar o status final da solicitação de E/S do objeto de arquivo.

RelatedFileObject

Um ponteiro para uma estrutura FILE_OBJECT usada para indicar que o objeto de arquivo atual foi aberto em relação a um objeto de arquivo já aberto. O objeto de arquivo apontado por esse membro geralmente é um diretório (o que significa que o arquivo atual foi aberto em relação a esse diretório). No entanto, um arquivo pode ser reaberto em relação a si mesmo e fluxos de dados alternativos para um arquivo podem ser abertos em relação a um fluxo de dados primário já aberto para esse mesmo arquivo. O membro RelatedFileObject só é válido durante o processamento das solicitações de IRP_MJ_CREATE .

LockOperation

Um membro somente leitura. Se FALSE, uma operação de bloqueio (NtLockFile) nunca foi executada no objeto de arquivo. Se TRUE, pelo menos uma operação de bloqueio foi executada no objeto de arquivo. Depois de definido como TRUE, esse membro sempre permanece TRUE (por exemplo, liberar bloqueios de arquivo no objeto de arquivo não redefine esse membro para FALSE).

DeletePending

Um membro somente leitura. Se TRUE, existirá uma operação de exclusão para o arquivo associado ao objeto de arquivo. Se FALSE, atualmente não há nenhuma operação de exclusão pendente para o objeto de arquivo.

ReadAccess

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para acesso de leitura. Se FALSE, o arquivo foi aberto sem acesso de leitura. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

WriteAccess

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para acesso de gravação. Se FALSE, o arquivo foi aberto sem acesso de gravação. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

DeleteAccess

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para acesso de exclusão. Se FALSE, o arquivo foi aberto sem acesso de exclusão. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

SharedRead

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para acesso de compartilhamento de leitura. Se FALSE, o arquivo foi aberto sem acesso de compartilhamento de leitura. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

SharedWrite

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para acesso de compartilhamento de gravação. Se FALSE, o arquivo foi aberto sem acesso de compartilhamento de gravação. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

SharedDelete

Um membro somente leitura. Se TRUE, o arquivo associado ao objeto de arquivo foi aberto para excluir o acesso de compartilhamento. Se FALSE, o arquivo foi aberto sem excluir o acesso de compartilhamento. Essas informações são usadas ao verificar e/ou definir o acesso de compartilhamento do arquivo.

Flags

Um membro somente leitura usado pelo sistema para manter um ou mais (uma combinação OR inclusiva bit a bit) dos seguintes valores de sinalizador privado.

Sinalizador Significado
FO_FILE_OPEN Preterido.
FO_SYNCHRONOUS_IO O objeto de arquivo é aberto para E/S síncrona.
FO_ALERTABLE_IO Qualquer espera no gerenciador de E/S, como resultado de uma solicitação feita a esse objeto de arquivo, é alertável.
FO_NO_INTERMEDIATE_BUFFERING O arquivo associado ao objeto de arquivo não pode ser armazenado em cache ou armazenado em buffers internos de um driver.
FO_WRITE_THROUGH Os serviços do sistema, os drivers do sistema de arquivos e os drivers que gravam dados no arquivo devem transferir os dados para o arquivo antes que qualquer operação de gravação solicitada seja considerada concluída.
FO_SEQUENTIAL_ONLY O arquivo associado ao objeto de arquivo foi aberto somente para operações de E/S sequenciais.
FO_CACHE_SUPPORTED O arquivo associado ao objeto de arquivo pode ser armazenado em cache. Esse sinalizador deve ser definido apenas por um driver do sistema de arquivos e somente se o membro FsContext apontar para uma estrutura de FSRTL_ADVANCED_FCB_HEADER válida.
FO_NAMED_PIPE O objeto de arquivo representa um pipe nomeado.
FO_STREAM_FILE O objeto de arquivo representa um fluxo de arquivos.
FO_MAILSLOT O objeto de arquivo representa um maillot.
FO_GENERATE_AUDIT_ON_CLOSE Preterido.
FO_QUEUE_IRP_TO_THREAD Os IRPs não serão enfileirados nesse objeto de arquivo.
FO_DIRECT_DEVICE_OPEN O dispositivo direcionado por esse objeto de arquivo foi aberto diretamente.
FO_FILE_MODIFIED O arquivo associado ao objeto de arquivo foi modificado.
FO_FILE_SIZE_CHANGED O arquivo associado ao objeto de arquivo foi alterado em tamanho.
FO_CLEANUP_COMPLETE O sistema de arquivos concluiu sua limpeza para esse objeto de arquivo.
FO_TEMPORARY_FILE O arquivo associado ao objeto de arquivo é um arquivo temporário.
FO_DELETE_ON_CLOSE O arquivo associado ao objeto de arquivo será excluído pelo sistema de arquivos após o fechamento.
FO_OPENED_CASE_SENSITIVE O caso de nome de arquivo do arquivo associado ao objeto de arquivo é respeitado.
FO_HANDLE_CREATED Um identificador de arquivo foi criado para o objeto de arquivo.
FO_FILE_FAST_IO_READ Uma leitura rápida de E/S foi executada neste objeto de arquivo.
FO_RANDOM_ACCESS O arquivo associado ao objeto de arquivo foi aberto para acesso aleatório.
FO_FILE_OPEN_CANCELLED A solicitação de criação para esse objeto de arquivo foi cancelada antes de ser concluída.
FO_VOLUME_OPEN O objeto de arquivo representa uma solicitação de abertura de volume.
FO_REMOTE_ORIGIN A solicitação de criação para o arquivo associado ao objeto de arquivo originou-se em um computador remoto.
FO_SKIP_COMPLETION_PORT Para um objeto de arquivo associado a uma porta, determina se o sistema deve ignorar o enfileiramento para a porta de conclusão quando o IRP for concluído de forma síncrona com um valor de retorno de não erro status.
FO_SKIP_SET_EVENT Ignore a configuração do evento para o objeto de arquivo após a conclusão do IRP.
FO_SKIP_SET_FAST_IO Ignore a configuração de um evento fornecido para um serviço do sistema quando o caminho de E/S rápido for bem-sucedido.

FileName

Uma estrutura UNICODE_STRING cujo membro Buffer aponta para uma cadeia de caracteres Unicode somente leitura que contém o nome do arquivo aberto no volume. Se o volume estiver sendo aberto, o membro Length da estrutura UNICODE_STRING será zero. Observe que o nome do arquivo nessa cadeia de caracteres é válido somente durante o processamento inicial de uma solicitação de IRP_MJ_CREATE . Esse nome de arquivo não deve ser considerado válido depois que o sistema de arquivos começar a processar a solicitação de IRP_MJ_CREATE . O armazenamento para a cadeia de caracteres apontada pelo membro Buffer da estrutura UNICODE_STRING é alocado na memória paginada do sistema. Para obter mais informações sobre como obter um nome de arquivo, consulte FltGetFileNameInformation.

CurrentByteOffset

Um membro somente leitura que especifica o deslocamento de arquivo, em bytes, associado ao objeto de arquivo.

Waiters

Um membro somente leitura usado pelo sistema para contar o número de garçons pendentes em um objeto de arquivo aberto para acesso síncrono.

Busy

Um membro somente leitura usado pelo sistema para indicar se um objeto de arquivo aberto para acesso síncrono está ocupado no momento.

LastLock

Um ponteiro opaco para o último bloqueio aplicado ao objeto de arquivo.

Lock

Um membro opaco usado pelo sistema para manter um bloqueio de evento de objeto de arquivo. O bloqueio de evento é usado para controlar o acesso síncrono ao objeto de arquivo. Aplicável somente a objetos de arquivo abertos para acesso síncrono.

Event

Um membro opaco usado pelo sistema para manter um objeto de evento para o objeto de arquivo. O objeto event é usado para sinalizar a conclusão de uma solicitação de E/S no objeto de arquivo se nenhum evento de usuário foi fornecido ou uma API síncrona foi chamada.

CompletionContext

Um ponteiro opaco para informações de porta de conclusão (ponteiro de porta e chave) associados ao objeto de arquivo, se houver.

IrpListLock

Um ponteiro opaco para uma estrutura KSPIN_LOCK que serve como o bloqueio de rotação usado para sincronizar o acesso à lista IRP do objeto de arquivo.

IrpList

Um ponteiro opaco para o cabeçalho da lista IRP associada ao objeto de arquivo.

FileObjectExtension

Um ponteiro opaco para a estrutura FOBX (extensão de objeto de arquivo) do objeto de arquivo. A estrutura FOBX contém vários contextos opacos usados internamente, bem como os contextos de objeto por arquivo disponíveis por meio de rotinas FsRtlXxx .

_IOP_FILE_OBJECT_EXTENSION

Uma estrutura _IOP_FILE_OBJECT_EXTENSION .

Comentários

Os drivers podem usar os membros FsContext e FsContext2 para manter o estado determinado pelo driver sobre um objeto de arquivo aberto. Um driver não pode usar esses membros, a menos que o objeto de arquivo esteja acessível no local da pilha de E/S do driver de um IRP.

Todos os membros restantes em um objeto de arquivo são opacos ou somente leitura:

  • Membros opacos dentro de um objeto de arquivo devem ser considerados inacessíveis. Drivers com dependências em locais de campo de objeto ou acesso a membros opacos podem não permanecer portáteis e interoperáveis com outros drivers ao longo do tempo.

  • Os drivers podem usar membros somente leitura para adquirir informações relevantes, mas não devem modificar membros somente leitura e, se um ponteiro, o objeto para o qual o membro aponta.

Durante o processamento de uma solicitação de IRP_MJ_CREATE , um driver do sistema de arquivos chama a rotina IoSetShareAccess (se o cliente for o primeiro a abrir o arquivo) ou a rotina IoCheckShareAccess (para clientes subsequentes que desejam compartilhar o arquivo). Os membros IoSetShareAccess e IoCheckShareAccess atualizam os membros ReadAccess, WriteAccess e DeleteAccess para indicar os direitos de acesso que são concedidos ao cliente se o cliente tiver acesso exclusivo ao arquivo. Além disso, IoCheckShareAccess atualiza os membros SharedRead, SharedWrite e SharedDelete para indicar os direitos de acesso que são concedidos simultaneamente a dois ou mais clientes que compartilham o arquivo. Se o driver de um dispositivo diferente de um sistema de arquivos precisar monitorar os direitos de acesso dos clientes, esse driver normalmente armazenará informações de direitos de acesso em buffers de contexto apontados pelos membros FsContext e FsContext2 .

O tipo de objeto (por exemplo, um arquivo, diretório ou volume) que um determinado objeto de arquivo representa não pode ser determinado examinando apenas o conteúdo da estrutura do objeto de arquivo. Para obter informações sobre como determinar o tipo de objeto que um objeto de arquivo representa, consulte ZwQueryInformationFile.

O CLFS (Common Log File System) usa a estrutura LOG_FILE_OBJECT para representar logs. A função ClfsCreateLogFile retorna um ponteiro para uma estrutura LOG_FILE_OBJECT , que os clientes passam para outras funções CLFS.

Os clientes CLFS não acessam diretamente os membros de uma estrutura LOG_FILE_OBJECT .

typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;

Requisitos

Requisito Valor
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)

Confira também

DEVICE_OBJECT

FOBX

FSRTL_ADVANCED_FCB_HEADER

IRP_MJ_CREATE

IoCheckShareAccess

IoGetDeviceObjectPointer

IoSetShareAccess

ObDereferenceObject

ZwQueryInformationFile