Fonction IoCreateStreamFileObjectEx2 (ntifs.h)

Article
03/01/2024

La routine IoCreateStreamFileObjectEx2 crée un objet de fichier de flux avec des options de création pour un objet d’appareil cible.

Syntaxe

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

Paramètres

[in] CreateOptions

Pointeur d’une structure IO_CREATE_STREAM_FILE_OPTIONS contenant les options de création pour l’objet de fichier de flux.

[in, optional] FileObject

Pointeur vers l’objet de fichier auquel le nouveau fichier de flux est lié. Ce paramètre est facultatif et peut être NULL.

[in, optional] DeviceObject

Pointeur vers un objet d’appareil pour l’appareil sur lequel le fichier de flux doit être ouvert. Si l’appelant spécifie une valeur non NULL pour FileObject, la valeur de DeviceObject est ignorée. Sinon, l’appelant doit spécifier une valeur non NULL pour DeviceObject.

[out] StreamFileObject

Pointeur vers un pointeur d’objet d’appareil pour recevoir l’objet fille de flux.

[out, optional] FileHandle

Pointeur vers un handle de fichier pour le flux de sortie. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

IoCreateStreamFileObjectEx2 retourne un pointeur vers l’objet de fichier de flux nouvellement créé.

Remarques

Les systèmes de fichiers appellent IoCreateStreamFileObjectEx2 pour créer un objet de fichier de flux. Un objet de fichier de flux est identique à un objet de fichier ordinaire, sauf que l’indicateur d’objet de fichier FO_STREAM_FILE est défini.

Un objet de fichier de flux est couramment utilisé pour représenter un flux interne pour un volume monté par le système de fichiers. Ce fichier de volume virtuel permet au système de fichiers d’afficher, de modifier et de mettre en cache la structure sur disque du volume comme s’il s’agissait d’un fichier ordinaire. Dans ce cas, le paramètre DeviceObject dans l’appel à IoCreateStreamFileObjectEx2 spécifie l’objet de périphérique de volume (VDO) pour le volume.

Un objet de fichier de flux peut également être utilisé pour représenter un autre flux de données pour accéder aux métadonnées d’un fichier, telles que des attributs étendus ou des descripteurs de sécurité. Dans ce cas, le paramètre FileObject dans l’appel à IoCreateStreamFileObjectEx2 spécifie un objet de fichier existant pour le fichier. L’objet de fichier stream nouvellement créé permet au système de fichiers d’afficher, de modifier et de mettre en cache les métadonnées du fichier comme s’il s’agissait d’un fichier ordinaire.

Lorsque l’objet de fichier de flux n’est plus nécessaire, l’appelant doit décrémenter son nombre de références en appelant ObDereferenceObject. Lorsque le nombre de références de l’objet de fichier de flux de flux atteint zéro, une requête IRP_MJ_CLOSE est envoyée à la pile de pilotes du système de fichiers pour le volume.

Les rédacteurs de pilotes de filtre de système de fichiers doivent noter qu’IoCreateStreamFileObjectEx2 provoque l’envoi d’une requête IRP_MJ_CLEANUP à la pile de pilotes du système de fichiers pour le volume. Étant donné que les systèmes de fichiers créent souvent des objets de fichier de flux en tant qu’effet secondaire d’opérations autres que IRP_MJ_CREATE, il est difficile pour les pilotes de filtre de détecter de manière fiable la création d’objets de fichiers de flux. Par conséquent, un pilote de filtre doit s’attendre à recevoirdes demandes de IRP_MJ_CLEANUP et de IRP_MJ_CLOSE pour des objets de fichier précédemment invisibles.

Si un échec d’allocation de pool se produit, IoCreateStreamFileObjectEx2 lève une exception STATUS_INSUFFICIENT_RESOURCES .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE