Fonction IoCancelFileOpen (ntddk.h)

Article
08/07/2023

La routine IoCancelFileOpen peut être utilisée par un pilote de filtre de système de fichiers pour fermer un fichier qui a été ouvert par un pilote de système de fichiers dans la pile de périphériques du pilote de filtre.

Syntaxe

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

Paramètres

[in] DeviceObject

Pointeur vers le haut de la pile de périphériques juste en dessous de l’objet de périphérique du pilote de filtre.

[in] FileObject

Pointeur vers l’objet file pour le fichier à fermer.

Valeur de retour

None

Remarques

Si un pilote de filtre de système de fichiers détermine qu’une demande d’ouverture ou de création de fichier doit échouer une fois que les pilotes de niveau inférieur ont déjà terminé la demande avec STATUS_SUCCESS, il peut utiliser IoCancelFileOpen pour fermer le fichier ouvert par les pilotes de niveau inférieur.

Bien que STATUS_REPARSE soit une valeur NTSTATUS réussie, il n’est pas nécessaire d’appeler IoCancelFileOpen pour une opération de création qui s’est terminée avec STATUS_REPARSE, car cette valeur status indique que le fichier n’a pas été correctement ouvert.

Un appel réussi à IoCancelFileOpen a l’effet suivant : Pour les minifiltres et les filtres hérités qui se trouvent au-dessus de l’appelant dans la pile du système de fichiers, la demande de création semble avoir échoué. Pour ceux qui se trouvent sous l’appelant, le fichier semble avoir été ouvert (ou créé), puis fermé.

Notez que IoCancelFileOpen n’annule aucune modification apportée au fichier. Par exemple, IoCancelFileOpen ne supprime pas un fichier nouvellement créé ou ne restaure pas un fichier qui a été remplacé ou remplacé à son état précédent.

Voici un exemple classique :

Un pilote de filtre existe entre un pilote de filtre de niveau supérieur et un pilote de système de fichiers de niveau inférieur.
Le pilote de filtre transmet une requête de IRP_MJ_CREATE dans la pile de périphériques au pilote de système de fichiers, et le pilote de système de fichiers termine la demande de IRP_MJ_CREATE avec status STATUS_SUCCESS.
Avant que le pilote de filtre termine la demande de création, il détermine que le fichier doit être fermé.
Le pilote de filtre utilise IoCancelFileOpen pour fermer le fichier ouvert par le pilote de système de fichiers.

Après avoir appelé IoCancelFileOpen, le pilote de filtre doit terminer la demande de création avec un code d’erreur approprié, tel que STATUS_UNSUCCESSFUL ou STATUS_ACCESS_DENIED. En outre, il doit définir le champ Irp-IoStatus.Information> sur zéro.

IoCancelFileOpen doit être appelé avant la création de handles pour le fichier. Les appelants peuvent case activée le membre Flags de la structure FILE_OBJECT vers laquelle pointe le paramètre FileObject. Si l’indicateur FO_HANDLE_CREATED est défini, cela signifie qu’un ou plusieurs descripteurs ont été créés pour le fichier. Il n’est donc pas sûr d’appeler IoCancelFileOpen.

IoCancelFileOpen définit l’indicateur FO_FILE_OPEN_CANCELLED dans le membre Flags de l’objet file vers lequel FileObject pointe. Cet indicateur indique que la demande IRP_MJ_CREATE a été annulée et qu’une demande de IRP_MJ_CLOSE sera émise pour cet objet de fichier. Une fois l’opération de création annulée, elle ne peut pas être rééditée, c’est-à-dire STATUS_REPARSE ne peut pas être retournée par le pilote de filtre hérité s’il a appelé la routine IoCreateFileOpen .

Les minifiltres doivent utiliser FltCancelFileOpen au lieu de IoCancelFileOpen.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Cette routine est disponible sur Microsoft Windows 2000 et versions ultérieures.
Plateforme cible	Universal
En-tête	ntddk.h (inclure Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL