Função IoCreateStreamFileObjectEx (ntifs.h)

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

Sintaxe

PFILE_OBJECT IoCreateStreamFileObjectEx(
  [in, optional]  PFILE_OBJECT   FileObject,
  [in, optional]  PDEVICE_OBJECT DeviceObject,
  [out, optional] PHANDLE        FileHandle
);

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.

[out, optional] FileHandle

Um ponteiro para um identificador de arquivo para o fluxo na saída. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

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

Comentários

Os sistemas de arquivos chamam IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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, IoCreateStreamFileObjectEx gerará uma exceção STATUS_INSUFFICIENT_RESOURCES.

Requisitos

Confira também

IRP_MJ_CLEANUP

IRP_MJ_CLOSE

IRP_MJ_CREATE

IoCreateStreamFileObject

IoCreateStreamFileObjectLite

ObDereferenceObject