Fonction IoBuildDeviceIoControlRequest (wdm.h)

Article
03/01/2024

La routine IoBuildDeviceIoControlRequest alloue et configure un IRP pour une demande de contrôle d’appareil traitée de manière synchrone.

Syntaxe

__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
  [in]            ULONG            IoControlCode,
  [in]            PDEVICE_OBJECT   DeviceObject,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength,
  [in]            BOOLEAN          InternalDeviceIoControl,
  [in, optional]  PKEVENT          Event,
  [out]           PIO_STATUS_BLOCK IoStatusBlock
);

Paramètres

[in] IoControlCode

Fournit le code de contrôle d’E/S (IOCTL) à utiliser dans la demande. Pour plus d’informations sur les codes de contrôle d’E/S spécifiques au type d’appareil, consultez les sections spécifiques au type d’appareil dans le Kit de pilotes Windows (WDK).

[in] DeviceObject

Fournit un pointeur vers la structure DEVICE_OBJECT pour l’objet de périphérique du pilote inférieur suivant, qui représente l’appareil cible.

[in, optional] InputBuffer

Fournit un pointeur vers une mémoire tampon d’entrée à passer au pilote inférieur, ou NULL si la requête ne transmet pas de données d’entrée aux pilotes inférieurs.

[in] InputBufferLength

Fournit la longueur, en octets, de la mémoire tampon d’entrée. Si InputBuffer a la valeur NULL, InputBufferLength doit être égal à zéro.

[out, optional] OutputBuffer

Fournit un pointeur vers une mémoire tampon de sortie dans laquelle le pilote inférieur doit retourner des données, ou NULL si la demande ne nécessite pas de pilotes inférieurs pour retourner des données.

[in] OutputBufferLength

Fournit la longueur, en octets, de la mémoire tampon de sortie. Si OutputBuffer a la valeur NULL, OutputBufferLength doit être égal à zéro.

[in] InternalDeviceIoControl

Si la valeur est TRUE, la routine définit le code de fonction principale de l’IRP sur IRP_MJ_INTERNAL_DEVICE_CONTROL. Sinon, la routine définit le code de fonction principal de l’IRP sur IRP_MJ_DEVICE_CONTROL.

[in, optional] Event

Fournit un pointeur vers un objet d’événement initialisé et alloué à l’appelant. Le gestionnaire d’E/S définit l’événement à l’état Signaled lorsqu’un pilote de niveau inférieur termine l’opération demandée. Après avoir appelé IoCallDriver, le pilote peut attendre l’objet d’événement. Le paramètre Event est facultatif et peut être défini sur NULL. Toutefois, si l’événement a la valeur NULL, l’appelant doit fournir une routine IoCompletion pour que l’IRP avertisse l’appelant à la fin de l’opération.

[out] IoStatusBlock

Spécifie un bloc d’E/S status à définir lorsque la demande est terminée par des pilotes inférieurs.

Valeur retournée

Si l’opération réussit, IoBuildDeviceIoControlRequest retourne un pointeur vers un IRP, avec l’emplacement de la pile d’E/S du pilote inférieur suivant configuré à partir des paramètres fournis. Sinon, la routine retourne NULL.

Remarques

Un pilote peut appeler IoBuildDeviceIoControlRequest pour configurer les irps pour les demandes de contrôle d’appareil qu’il envoie de manière synchrone aux pilotes de niveau inférieur.

Après avoir appelé IoBuildDeviceIoControlRequest pour créer une requête, le pilote doit appeler IoCallDriver pour envoyer la demande au pilote inférieur suivant. Si IoCallDriver retourne STATUS_PENDING, le pilote doit attendre la fin de l’IRP en appelant KeWaitForSingleObject sur l’événement donné. La plupart des pilotes n’ont pas besoin de définir une routine IoCompletion pour l’IRP.

Les IIP créés par IoBuildDeviceIoControlRequest doivent être complétés par un appel de pilote à IoCompleteRequest. Un pilote qui appelle IoBuildDeviceIoControlRequest ne doit pas appeler IoFreeIrp, car le gestionnaire d’E/S libère ces IRP synchrones après l’appel d’IoCompleteRequest .

IoBuildDeviceIoControlRequest met en file d’attente les IRP qu’il crée dans une file d’attente IRP spécifique au thread actif. Si le thread se ferme, le gestionnaire d’E/S annule l’IRP.

Si l’appelant fournit un paramètre InputBuffer ou OutputBuffer , ce paramètre doit pointer vers une mémoire tampon qui réside dans la mémoire système. L’appelant est responsable de la validation des valeurs de paramètre qu’il copie dans la mémoire tampon d’entrée à partir d’une mémoire tampon en mode utilisateur. La mémoire tampon d’entrée peut contenir des valeurs de paramètres qui sont interprétées différemment selon que l’initiateur de la requête est une application en mode utilisateur ou un pilote en mode noyau. Dans l’IRP retourné par IoBuildDeviceIoControlRequest , le champ RequestorMode est toujours défini sur KernelMode. Cette valeur indique que la demande et toutes les informations contenues dans la demande proviennent d’un composant approuvé en mode noyau.

Si l’appelant ne peut pas valider les valeurs de paramètre qu’il copie d’une mémoire tampon en mode utilisateur vers la mémoire tampon d’entrée, ou si ces valeurs ne doivent pas être interprétées comme provenant d’un composant en mode noyau, l’appelant doit définir le champ RequestorMode dans l’IRP sur UserMode. Ce paramètre informe le pilote qui gère la demande de contrôle d’E/S que la mémoire tampon contient des données non approuvées en mode utilisateur.

La méthode réelle par laquelle le contenu des paramètres InputBuffer et OutputBuffer est stocké dans l’IRP dépend de la valeur TransferType pour le IOCTL. Pour plus d’informations sur cette valeur, consultez Description de la mémoire tampon pour les codes de contrôle d’E/S.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm),IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)