Fonction NtFsControlFile (ntifs.h)
La routine NtFsControlFile envoie un code de contrôle directement à un pilote de filtre de système de fichiers ou de système de fichiers spécifié, ce qui entraîne l’exécution de l’action spécifiée par le pilote correspondant.
Syntaxe
__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG FsControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
Paramètres
[in] FileHandle
Handle retourné par NtCreateFile ou NtOpenFile pour l’objet de fichier représentant le fichier ou le répertoire sur lequel l’action spécifiée doit être effectuée. L’objet de fichier doit avoir été ouvert pour les E/S asynchrones si l’appelant spécifie und’événement
[in, optional] Event
Handle pour un événement créé par l’appelant. Si ce paramètre est fourni, l’appelant est placé dans un état d’attente jusqu’à ce que l’opération demandée soit terminée et que l’événement donné soit défini sur l’état Signaled. Ce paramètre est facultatif et peut être NULL. Elle doit être NULL si l’appelant attend que le FileHandle soit défini sur l’état Signaled.
[in, optional] ApcRoutine
Adresse d’une routine APC fournie par l’appelant à appeler une fois l’opération demandée terminée. Ce paramètre est facultatif et peut être NULL. Elle doit être NULL s’il existe un objet d’achèvement d’E/S associé à l’objet fichier.
[in, optional] ApcContext
Pointeur vers une zone de contexte déterminée par l’appelant. Cette valeur de paramètre est utilisée comme contexte APC si l’appelant fournit un APC, ou est utilisée comme contexte d’achèvement si un objet d’achèvement d’E/S a été associé à l’objet de fichier. Une fois l’opération terminée, soit le contexte APC est transmis à l’APC, s’il a été spécifié, soit le contexte d’achèvement est inclus dans le message de saisie semi-automatique que le Gestionnaire d’E/S publie sur l’objet d’achèvement d’E/S associé.
Ce paramètre est facultatif et peut être NULL. Elle doit être NULL si ApcRoutine a la valeur NULL et qu’aucun objet d’achèvement d’E/S n’est associé à l’objet de fichier.
[out] IoStatusBlock
Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et les informations sur l’opération. Pour les appels réussis qui retournent des données, le nombre d’octets écrits dans le OutputBuffer
[in] FsControlCode
FSCTL_
[in, optional] InputBuffer
Pointeur vers une mémoire tampon d’entrée allouée par l’appelant qui contient des informations spécifiques à l’appareil à donner au pilote cible. Si FsControlCode spécifie une opération qui ne nécessite pas de données d’entrée, ce pointeur est facultatif et peut être NULL.
[in] InputBufferLength
Taille, en octets, de la mémoire tampon à InputBuffer. Cette valeur est ignorée si InputBuffer a la valeur NULL.
[out, optional] OutputBuffer
Pointeur vers une mémoire tampon de sortie allouée par l’appelant dans laquelle les informations sont retournées par le pilote cible. Si FsControlCode spécifie une opération qui ne produit pas de données de sortie, ce pointeur est facultatif et peut être NULL.
[in] OutputBufferLength
Taille, en octets, de la mémoire tampon à OutputBuffer. Cette valeur est ignorée si OutputBuffer a la valeur NULL.
Valeur de retour
NtFsControlFile retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des suivantes :
Remarques
NtFsControlFile fournit une vue cohérente des données d’entrée et de sortie au système et aux pilotes en mode noyau, tout en fournissant aux applications et aux pilotes sous-jacents une méthode dépendante du pilote pour spécifier une interface de communication.
Si l’appelant a ouvert le fichier pour les E/S asynchrones (sans FILE_SYNCHRONOUS_xxx'option create/open), l’événement spécifié, le cas échéant, est défini sur l’état signalé lorsque l’opération de contrôle de l’appareil se termine. Dans le cas contraire, l’objet de fichier spécifié par FileHandle sera défini sur l’état signalé. Si une
Voici quelques-uns des codes FSCTL documentés pour les pilotes en mode noyau :
- FSCTL_DELETE_REPARSE_POINT
- FSCTL_GET_REPARSE_POINT
- FSCTL_OPBATCH_ACK_CLOSE_PENDING
- FSCTL_OPLOCK_BREAK_ACK_NO_2
- FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
- FSCTL_OPLOCK_BREAK_NOTIFY
- FSCTL_REQUEST_BATCH_OPLOCK
- FSCTL_REQUEST_FILTER_OPLOCK
- FSCTL_REQUEST_OPLOCK_LEVEL_1
- FSCTL_REQUEST_OPLOCK_LEVEL_2
- FSCTL_SET_REPARSE_POINT
Pour plus d’informations sur les codes FSCTL_de xxx définis par le système, consultez la section « Remarques » de DeviceIoControl, qui est généralement utilisée par les applications en mode utilisateur.
Pour plus d’informations sur les codes IOCTL_
Les minifiltres doivent utiliser fltFsControlFile au lieu de NtFsControlFile .
Les appelants de NtFsControlFile doivent s’exécuter à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.
Si l’appel à la fonction NtFsControlFile se produit en mode utilisateur, vous devez utiliser le nom «NtFsControlFile» au lieu de «ZwFsControlFile».
Pour les appels à partir de pilotes en mode noyau, les versions NtXXX et ZwXXX d’une routine Windows Native System Services peuvent se comporter différemment de la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre la NtXXX et ZwXXX versions d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 |
| plateforme cible | Universel |
| d’en-tête | ntifs.h (include Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (voir la section Remarques) |
| règles de conformité DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |