IoCreateStreamFileObject-Funktion (ntifs.h)

Artikel
02/07/2025

Die IoCreateStreamFileObject Routine erstellt ein neues Streamdateiobjekt.

Syntax

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

Parameter

[in, optional] FileObject

Zeigen Sie auf das Dateiobjekt, mit dem die neue Datenstromdatei verknüpft ist. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] DeviceObject

Zeigen Sie auf ein Geräteobjekt für das Gerät, auf dem die Streamdatei geöffnet werden soll. Wenn der Aufrufer einen Wert ungleichNULL für FileObject-angibt, wird der Wert DeviceObject- ignoriert. Andernfalls muss der Aufrufer einen Wert ohneNULL- für DeviceObject-angeben.

Rückgabewert

IoCreateStreamFileObject gibt einen Zeiger auf das neu erstellte Streamdateiobjekt zurück.

Bemerkungen

Dateisysteme rufen IoCreateStreamFileObject auf, um ein neues Streamdateiobjekt zu erstellen. Ein Streamdateiobjekt ist identisch mit einem normalen Dateiobjekt, mit der Ausnahme, dass das FO_STREAM_FILE Dateiobjekt-Flag festgelegt ist.

Ein Streamdateiobjekt wird häufig verwendet, um einen internen Datenstrom für ein vom Dateisystem bereitgestelltes Volume darzustellen. Diese virtuelle Volumedatei ermöglicht es dem Dateisystem, die Struktur des Volumes auf dem Datenträger anzuzeigen, zu ändern und zwischenzuspeichern, als wäre es eine normale Datei. In diesem Fall gibt der parameter DeviceObject im Aufruf von IoCreateStreamFileObject das Volumegeräteobjekt (Volume Device Object, VDO) für das Volume an.

Ein Streamdateiobjekt kann auch verwendet werden, um einen alternativen Datenstrom für den Zugriff auf die Metadaten einer Datei darzustellen, z. B. erweiterte Attribute oder Sicherheitsdeskriptoren. In diesem Fall gibt der parameter FileObject im Aufruf von IoCreateStreamFileObject ein vorhandenes Dateiobjekt für die Datei an. Das neu erstellte Streamdateiobjekt ermöglicht es dem Dateisystem, die Metadaten der Datei anzuzeigen, zu ändern und zwischenzuspeichern, als wäre es eine normale Datei.

Wenn das Streamdateiobjekt nicht mehr benötigt wird, muss der Aufrufer seine Verweisanzahl durch Aufrufen von ObDereferenceObjecterhöhen. Wenn die Referenzanzahl des Datenstromdateiobjekts null erreicht, wird eine IRP_MJ_CLOSE Anforderung an den Dateisystemtreiberstapel für das Volume gesendet.

Autoren des Dateisystemfiltertreibers sollten beachten, dass IoCreateStreamFileObject- bewirkt, dass eine IRP_MJ_CLEANUP Anforderung an den Dateisystemtreiberstapel für das Volume gesendet wird. Da Dateisysteme häufig Streamdateiobjekte als Nebenwirkung anderer Vorgänge als IRP_MJ_CREATE erstellen, ist es für Filtertreiber schwierig, die Erstellung von Datenstromobjekten zuverlässig zu erkennen. Daher sollte ein Filtertreiber erwarten, dass IRP_MJ_CLEANUP und IRP_MJ_CLOSE Anforderungen für zuvor nicht angezeigte Dateiobjekte empfangen werden.

Wenn ein Poolzuordnungsfehler auftritt, löst IoCreateStreamFileObject eine STATUS_INSUFFICIENT_RESOURCES Ausnahme aus.