Fonction ZwDeviceIoControlFile (ntifs.h)
La routine ZwDeviceIoControlFile envoie un code de contrôle directement à un pilote de périphérique spécifié, ce qui entraîne l’exécution de l’opération spécifiée par le pilote correspondant.
Syntaxe
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
Paramètres
[in] FileHandle
Handle retourné par ZwCreateFile ou ZwOpenFile pour l’objet de fichier représentant l’appareil auquel les informations de contrôle doivent être fournies ou à partir duquel les informations doivent être retournées. L’objet file doit avoir été ouvert pour les E/S asynchrones si l’appelant spécifie un event, ApcRoutine et un contexte APC (dans ApcContext) ou un contexte d’achèvement (dans ApcContext). Pour les E/S sur un appareil de stockage de masse sous-jacent, l’objet fichier doit avoir été ouvert pour l’accès direct au périphérique de stockage (DASD).
[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 fileHandle soit défini sur l’état Signaled.
[in, optional] ApcRoutine
Adresse d’une routine APC fournie par l’appelant facultative à appeler une fois l’opération demandée terminée. Ce paramètre peut être NULL. Il 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 fichier. Une fois l’opération terminée, soit le contexte APC est passé à l’APC, le cas échéant, soit le contexte d’achèvement est inclus dans le message d’achèvement 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 fichier.
[out] IoStatusBlock
Pointeur vers une variable qui reçoit l’achèvement final status et des informations sur l’opération. Pour les appels réussis qui retournent des données, le nombre d’octets écrits dans OutputBuffer est retourné dans le membre Information .
[in] IoControlCode
IOCTL_ codeXXX qui indique quelle opération de contrôle d’E/S d’appareil doit être effectuée, généralement par le pilote de périphérique sous-jacent. La valeur de ce paramètre détermine le format et la longueur requise de InputBuffer et OutputBuffer, ainsi que les paires de paramètres suivantes requises. Pour plus d’informations sur les codes IOCTL_XXX définis par le système et spécifiques au type d’appareil, consultez la section relative à la technologie de l’appareil de la documentation du Kit de pilotes Microsoft Windows (WDK) et les codes de contrôle d’entrée et de sortie d’appareil dans la documentation du Microsoft Windows SDK.
[in, optional] InputBuffer
Pointeur vers une mémoire tampon d’entrée allouée à l’appelant qui contient des informations spécifiques à l’appareil à donner à l’appareil cible. Si IoControlCode spécifie une opération qui ne nécessite pas de données d’entrée, ce pointeur peut avoir la valeur NULL.
[in] InputBufferLength
Taille, en octets, de la mémoire tampon sur InputBuffer. Si InputBuffer a la valeur NULL, définissez InputBufferLength sur zéro.
[out, optional] OutputBuffer
Pointeur vers une mémoire tampon de sortie allouée à l’appelant dans laquelle les informations sont retournées à partir de l’appareil cible. Si IoControlCode spécifie une opération qui ne produit pas de données de sortie, ce pointeur peut avoir la valeur NULL.
[in] OutputBufferLength
Taille, en octets, de la mémoire tampon dans OutputBuffer. Si OutputBuffer a la valeur NULL, définissez OutputBufferLength sur zéro.
Valeur retournée
ZwDeviceIoControlFile retourne STATUS_SUCCESS si le ou les pilotes sous-jacents ont correctement effectué l’opération demandée. Sinon, la valeur de retour peut être une erreur status code propagé à partir d’un pilote sous-jacent. Les codes de status d’erreur possibles incluent les éléments suivants :
Remarques
ZwDeviceIoControlFile fournit une vue cohérente des données d’entrée et de sortie sur le système et sur les pilotes en mode noyau, tout en fournissant aux applications et aux pilotes sous-jacents une méthode dépendante de l’appareil pour spécifier une interface de communication.
Pour plus d’informations sur les codes IOCTL_XXX définis par le système et sur la définition de valeurs IOCTL_XXX ou FSCTL_XXX spécifiques au pilote, consultez Utilisation de codes de contrôle d’E/S dans le Guide de l’architecture en mode noyau et Codes de contrôle d’entrée et de sortie d’appareil dans la documentation du Microsoft Windows SDK.
Si l’appelant a ouvert le fichier pour les E/S asynchrones (sans FILE_SYNCHRONOUS_XXX create/open option set), l’événement spécifié, le cas échéant, est défini à l’état signalé une fois l’opération de contrôle de l’appareil terminée. Sinon, l’objet de fichier spécifié par FileHandle sera défini à l’état signalé. Si un ApcRoutine a été spécifié, il est appelé avec les pointeurs ApcContext et IoStatusBlock .
Les minifiltres doivent utiliser FltDeviceIoControlFile au lieu de ZwDeviceIoControlFile.
Les appelants de ZwDeviceIoControlFile doivent être en cours d’exécution à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000. |
| Plateforme cible | Universal |
| En-tête | ntifs.h (inclure Ntifs.h, Ntddk.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (voir la section Remarques) |
| Règles de conformité DDI | HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm) |
Voir aussi
Utilisation de codes de contrôle d’E/S
Utilisation des versions Nt et Zw des routines natives des services système natifs