Função IoCreateStreamFileObjectEx2 (ntifs.h)

A rotina IoCreateStreamFileObjectEx2 cria um novo objeto de arquivo de fluxo com opções de criação para um objeto de dispositivo de destino.

Sintaxe

NTSTATUS IoCreateStreamFileObjectEx2(
  [in]            PIO_CREATE_STREAM_FILE_OPTIONS CreateOptions,
  [in, optional]  PFILE_OBJECT                   FileObject,
  [in, optional]  PDEVICE_OBJECT                 DeviceObject,
  [out]           PFILE_OBJECT                   *StreamFileObject,
  [out, optional] PHANDLE                        FileHandle
);

Parâmetros

[in] CreateOptions

Ponteiro uma estrutura de IO_CREATE_STREAM_FILE_OPTIONS que contém as opções de criação para o novo objeto de arquivo de fluxo.

[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] StreamFileObject

Ponteiro para um ponteiro de objeto do dispositivo para receber o objeto de arquivo de fluxo.

[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

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

Comentários

Os sistemas de arquivos chamam IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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 IIRP_MJ_CLEANUP e IRP_MJ_CLOSE para objetos de arquivo não vistos anteriormente.

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

Requisitos

Confira também

IRP_MJ_CLEANUP

IRP_MJ_CLOSE

IRP_MJ_CREATE

IoCreateStreamFileObject

IoCreateStreamFileObjectEx

IoCreateStreamFileObjectLite

ObDereferenceObject