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) |