IoCreateStreamFileObjectEx2-Funktion (ntifs.h)

Artikel
07/11/2023

Die IoCreateStreamFileObjectEx2-Routine erstellt ein neues Streamdateiobjekt mit Erstellungsoptionen für ein Zielgerätobjekt.

Syntax

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

Parameter

[in] CreateOptions

Zeiger auf eine IO_CREATE_STREAM_FILE_OPTIONS-Struktur , die die Erstellungsoptionen für das neue Streamdateiobjekt enthält.

[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 ohne NULL für FileObject angibt, wird der Wert von DeviceObject ignoriert. Andernfalls muss der Aufrufer einen Wert ohne NULL für DeviceObject angeben.

[out] StreamFileObject

Zeiger auf einen Geräteobjektzeiger, um das Stream fille-Objekt zu empfangen.

[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

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

Hinweise

Dateisysteme rufen IoCreateStreamFileObjectEx2 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 Stream für ein vom Dateisystem eingebundenes Volume darzustellen. Diese Datei des virtuellen Volumes 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 IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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-Autoren sollten beachten, dass IoCreateStreamFileObjectEx2 bewirkt, dass eine IRP_MJ_CLEANUP Anforderung an den Dateisystemtreiberstapel für das Volume gesendet wird. Da Dateisysteme häufig Streamdateiobjekte als Nebeneffekt anderer Vorgänge 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 ichIRP_MJ_CLEANUP und IRP_MJ_CLOSE Anforderungen für zuvor nicht angezeigte Dateiobjekte empfängt.

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

Anforderungen

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