Função IoCreateStreamFileObject (ntifs.h)

Artigo
08/07/2023

A rotina IoCreateStreamFileObject cria um novo objeto de arquivo de fluxo.

Sintaxe

PFILE_OBJECT IoCreateStreamFileObject(
  [in, optional] PFILE_OBJECT   FileObject,
  [in, optional] PDEVICE_OBJECT DeviceObject
);

Parâmetros

[in, optional] FileObject

Ponteiro para o objeto de arquivo ao qual o novo arquivo de fluxo está relacionado. Esse parâmetro é opcional e pode ser NULL.

[in, optional] DeviceObject

Ponteiro para um objeto de dispositivo para o dispositivo no qual o arquivo de fluxo deve ser aberto. Se o chamador especificar um valor não NULL para FileObject, o valor de DeviceObject será ignorado. Caso contrário, o chamador deve especificar um valor não NULL para DeviceObject.

Retornar valor

IoCreateStreamFileObject retorna um ponteiro para o objeto de arquivo de fluxo recém-criado.

Comentários

Os sistemas de arquivos chamam IoCreateStreamFileObject para criar um novo objeto de arquivo de fluxo. Um objeto de arquivo de fluxo é idêntico a um objeto de arquivo comum, exceto que o sinalizador de objeto de arquivo FO_STREAM_FILE está definido.

Um objeto de arquivo de fluxo é comumente usado para representar um fluxo interno para um volume montado pelo sistema de arquivos. Esse arquivo de volume virtual permite que o sistema de arquivos exiba, altere e armazene em cache a estrutura em disco do volume como se fosse um arquivo comum. Nesse caso, o parâmetro DeviceObject na chamada para IoCreateStreamFileObject especifica o VDO (objeto de dispositivo de volume) para o volume.

Um objeto de arquivo de fluxo também pode ser usado para representar um fluxo de dados alternativo para acessar os metadados de um arquivo, como atributos estendidos ou descritores de segurança. Nesse caso, o parâmetro FileObject na chamada para IoCreateStreamFileObject especifica um objeto de arquivo existente para o arquivo. O objeto de arquivo de fluxo recém-criado permite que o sistema de arquivos exiba, altere e armazene em cache os metadados do arquivo como se fosse um arquivo comum.

Quando o objeto de arquivo de fluxo não é mais necessário, o chamador deve diminuir sua contagem de referência chamando ObDereferenceObject. Quando a contagem de referência do objeto de arquivo de fluxo atinge zero, uma solicitação IRP_MJ_CLOSE é enviada para a pilha de driver do sistema de arquivos para o volume.

Os gravadores de driver de filtro do sistema de arquivos devem observar que IoCreateStreamFileObject faz com que uma solicitação IRP_MJ_CLEANUP seja enviada para a pilha de driver do sistema de arquivos para o volume. Como os sistemas de arquivos geralmente criam objetos de arquivo de fluxo como um efeito colateral de operações diferentes de IRP_MJ_CREATE, é difícil para os drivers de filtro detectar de forma confiável a criação de objeto de arquivo de fluxo. Portanto, um driver de filtro deve esperar receber solicitações de IRP_MJ_CLEANUP e IRP_MJ_CLOSE para objetos de arquivo não vistos anteriormente.

Se ocorrer uma falha de alocação de pool, IoCreateStreamFileObject gerará uma exceção STATUS_INSUFFICIENT_RESOURCES.