Funzione IoCreateStreamFileObjectEx2 (ntifs.h)

Articolo
07/11/2023

La routine IoCreateStreamFileObjectEx2 crea un nuovo oggetto file di flusso con opzioni di creazione per un oggetto dispositivo di destinazione.

Sintassi

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

Parametri

[in] CreateOptions

Puntatore a una struttura IO_CREATE_STREAM_FILE_OPTIONS contenente le opzioni di creazione per il nuovo oggetto file di flusso.

[in, optional] FileObject

Puntatore all'oggetto file a cui è correlato il nuovo file di flusso. Questo parametro è facoltativo e può essere NULL.

[in, optional] DeviceObject

Puntatore a un oggetto dispositivo per il dispositivo in cui deve essere aperto il file di flusso. Se il chiamante specifica un valore non NULL per FileObject, il valore di DeviceObject viene ignorato. In caso contrario, il chiamante deve specificare un valore non NULL per DeviceObject.

[out] StreamFileObject

Puntatore a un puntatore a un oggetto dispositivo per ricevere l'oggetto riempimento del flusso.

[out, optional] FileHandle

Puntatore a un handle di file per il flusso nell'output. Questo parametro è facoltativo e può essere NULL.

Valore restituito

IoCreateStreamFileObjectEx2 restituisce un puntatore all'oggetto file di flusso appena creato.

Commenti

I file system chiamano IoCreateStreamFileObjectEx2 per creare un nuovo oggetto file di flusso. Un oggetto file di flusso è identico a un oggetto file normale, ad eccezione del fatto che il flag dell'oggetto file FO_STREAM_FILE è impostato.

Un oggetto file di flusso viene comunemente usato per rappresentare un flusso interno per un volume montato dal file system. Questo file di volume virtuale consente al file system di visualizzare, modificare e memorizzare nella cache la struttura del volume su disco come se fosse un file normale. In questo caso, il parametro DeviceObject nella chiamata a IoCreateStreamFileObjectEx2 specifica l'oggetto dispositivo del volume (VDO) per il volume.

Un oggetto file di flusso può essere usato anche per rappresentare un flusso di dati alternativo per accedere ai metadati di un file, ad esempio attributi estesi o descrittori di sicurezza. In questo caso, il parametro FileObject nella chiamata a IoCreateStreamFileObjectEx2 specifica un oggetto file esistente per il file. L'oggetto file di flusso appena creato consente al file system di visualizzare, modificare e memorizzare nella cache i metadati del file come se fosse un file normale.

Quando l'oggetto file di flusso non è più necessario, il chiamante deve decrementare il numero di riferimenti chiamando ObDereferenceObject. Quando il numero di riferimenti dell'oggetto file di flusso raggiunge zero, viene inviata una richiesta di IRP_MJ_CLOSE allo stack di driver del file system per il volume.

I writer del driver di filtro del file system devono notare che IoCreateStreamFileObjectEx2 causa l'invio di una richiesta di IRP_MJ_CLEANUP allo stack di driver del file system per il volume. Poiché i file system spesso creano oggetti file di flusso come effetto collaterale delle operazioni diverse da IRP_MJ_CREATE, è difficile che i driver di filtro rilevino in modo affidabile la creazione di oggetti file di flusso. Pertanto, un driver di filtro dovrebbe ricevereIRP_MJ_CLEANUP e IRP_MJ_CLOSE richieste di oggetti file non visualizzati in precedenza.

Se si verifica un errore di allocazione del pool, IoCreateStreamFileObjectEx2 genera un'eccezione STATUS_INSUFFICIENT_RESOURCES .

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVO