IoCreateStreamFileObjectEx-Funktion (ntifs.h)

Artikel
02/29/2024

Die IoCreateStreamFileObjectEx-Routine erstellt ein neues Streamdateiobjekt.

Syntax

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

Parameter

[in, optional] FileObject

Zeiger auf das Dateiobjekt, mit dem die neue Streamdatei verknüpft ist. Dieser Parameter ist optional und kann NULL sein.

[in, optional] DeviceObject

Zeiger auf ein Geräteobjekt für das Gerät, auf dem die Streamdatei geöffnet werden soll. Wenn der Aufrufer einen Wert ungleich NULL für FileObject angibt, wird der Wert von DeviceObject ignoriert. Andernfalls muss der Aufrufer einen Wert ungleich NULL für DeviceObject angeben.

[out, optional] FileHandle

Ein Zeiger auf ein Dateihandle für den Stream bei der Ausgabe. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

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

Hinweise

Dateisysteme rufen IoCreateStreamFileObjectEx auf, um ein neues Streamdateiobjekt zu erstellen. Ein Streamdateiobjekt ist mit einem gewöhnlichen Dateiobjekt identisch, mit der Ausnahme, dass das FO_STREAM_FILE Dateiobjektflag festgelegt ist.

Ein Streamdateiobjekt wird häufig verwendet, um einen internen Datenstrom für ein volume darzustellen, das vom Dateisystem bereitgestellt wird. 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 DeviceObject-Parameter im Aufruf von IoCreateStreamFileObjectEx das 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 Sicherheitsbeschreibungen. In diesem Fall gibt der FileObject-Parameter im Aufruf von IoCreateStreamFileObjectEx 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 ob es sich um eine normale Datei handelt.

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

Dateisystemfiltertreiber-Writer sollten beachten, dass IoCreateStreamFileObjectEx bewirkt, dass eine IRP_MJ_CLEANUP-Anforderung an den Dateisystemtreiberstapel für das Volume gesendet wird. Da Dateisysteme häufig Streamdateiobjekte als Nebeneffekt von Vorgängen als IRP_MJ_CREATE erstellen, ist es für Filtertreiber schwierig, die Erstellung von Streamdateiobjekten zuverlässig zu erkennen. Daher sollte ein Filtertreiber erwarten, dass er IRP_MJ_CLEANUP und IRP_MJ_CLOSE Anforderungen für zuvor nicht angezeigte Dateiobjekte empfängt.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE