Funzione IoCreateStreamFileObject (ntifs.h)

Articolo
08/07/2023

La routine IoCreateStreamFileObject crea un nuovo oggetto file di flusso.

Sintassi

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

Parametri

[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.

Valore restituito

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

Commenti

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

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 su disco del volume come se fosse un file normale. In questo caso, il parametro DeviceObject nella chiamata a IoCreateStreamFileObject 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 IoCreateStreamFileObject 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 IRP_MJ_CLOSE allo stack di driver del file system per il volume.

I writer dei driver di filtro del file system devono notare che IoCreateStreamFileObject 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 per i driver di filtro rilevare in modo affidabile la creazione di oggetti file di flusso. Pertanto, un driver di filtro dovrebbe ricevere IRP_MJ_CLEANUP e IRP_MJ_CLOSE richieste di oggetti file non visualizzati in precedenza.

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

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL