Funzione IoCreateStreamFileObjectEx (ntifs.h)

Articolo
03/08/2023

La routine IoCreateStreamFileObjectEx crea un nuovo oggetto file di flusso.

Sintassi

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

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.

[out, optional] FileHandle

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

Valore restituito

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

Commenti

I file system chiamano IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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 IoCreateStreamFileObjectEx 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, IoCreateStreamFileObjectEx genera un'eccezione STATUS_INSUFFICIENT_RESOURCES.

Requisiti

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