ZwDeviceIoControlFile, fonction (ntifs.h)

Article
12/22/2024

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 de laquelle les informations doivent être retournées. L’objet de fichier doit avoir été ouvert pour les E/S asynchrones si l’appelant spécifie und’événement , ApcRoutineet un contexte APC (dans ApcContext) ou un contexte d’achèvement (dans ApcContext). Pour les E/S vers un appareil de stockage en masse sous-jacent, l’objet fichier doit avoir été ouvert pour l’accès direct à l’appareil 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 le FileHandle soit défini sur l’état Signaled.

[in, optional] ApcRoutine

Adresse d’une routine APC facultative fournie par l’appelant à 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 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. Il doit être NULL si ApcRoutine est NULL et qu’aucun objet d’achèvement d’E/S n’est associé à l’objet de fichier.

[out] IoStatusBlock

Pointeur vers une variable qui reçoit l’état d’achèvement final et les informations relatives à l’opération. Pour les appels réussis qui retournent des données, le nombre d’octets écrits dans le OutputBuffer est retourné dans le membre Information.

[in] IoControlCode

IOCTL_code de XXX qui indique l’opération de contrôle d’E/S de l’appareil à effectuer, 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 des InputBuffer et OutputBuffer, ainsi que les paires de paramètres suivantes. Pour plus d’informations sur les codes de XXX IOCTL_spécifiques au type d’appareil définis par le système, consultez la section technologie d’appareil de la documentation du Kit de pilotes Microsoft Windows (WDK) et Codes de contrôle d’entrée et de sortie de périphérique dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows.

[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 à attribuer à l’appareil cible. Si IoControlCode spécifie une opération qui ne nécessite pas de données d’entrée, ce pointeur peut être NULL.

[in] InputBufferLength

Taille, en octets, de la mémoire tampon à InputBuffer. Si InputBuffer est NULL, définissez InputBufferLength sur zéro.

[out, optional] OutputBuffer

Pointeur vers une mémoire tampon de sortie allouée par 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 être NULL .

[in] OutputBufferLength

Taille, en octets, de la mémoire tampon à OutputBuffer. Si OutputBuffer est NULL, définissez OutputBufferLength sur zéro.

Valeur de retour

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 un code d’état d’erreur propagé à partir d’un pilote sous-jacent. Les codes d’état d’erreur possibles sont les suivants :

Remarques

ZwDeviceIoControlFile 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 des applications et des pilotes sous-jacents avec une méthode dépendante de l’appareil pour spécifier une interface de communication.

Pour plus d’informations sur les codes IOCTL_de XXX définis par le système et sur la définition de IOCTL_ XXX ou de valeurs FSCTL_XXX spécifiques au pilote, consultez Utilisation des codes de contrôle d’E/S dans le guide d’architecture du mode noyau et codes de contrôle d’entrée et de sortie de périphérique dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows.

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 ApcRoutine a été spécifiée, elle est appelée avec les pointeurs ApcContext et IoStatusBlock.

Les minifilters doivent utiliser FltDeviceIoControlFile au lieu de ZwDeviceIoControlFile.

Les appelants de ZwDeviceIoControlFile doivent s’exécuter à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Remarque Si l’appel à la fonction ZwDeviceIoControlFile se produit en mode utilisateur, vous devez utiliser le nom «NtDeviceIoControlFile» au lieu de «ZwDeviceIoControlFile».

Pour les appels à partir de pilotes en mode noyau, les versions **Nt*Xxx*** et **Zw*Xxx*** 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 les versions **Nt*Xxx*** et **Zw*Xxx*** d’une routine, consultez [Using Nt and Zw Versions of the Native System Services Routines](/windows-hardware/drivers/kernel/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, 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)