WdfIoTargetSendInternalIoctlSynchronously, fonction (wdfiotarget.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

La méthode WdfIoTargetSendInternalIoctlSynchronously génère une demande de contrôle d’appareil interne et l’envoie de manière synchrone à une cible d’E/S.

Syntaxe

NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

Paramètres

[in] IoTarget

Handle vers un objet cible d’E/S local ou distant qui a été obtenu à partir d’un appel précédent à WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou à partir d’une méthode qu’une cible d’E/S spécialisée fournit.

[in, optional] Request

Handle d’un objet de requête d’infrastructure. Ce paramètre est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in] IoctlCode

Code de contrôle d’E/S (IOCTL) pris en charge par la cible d’E/S.

[in, optional] InputBuffer

Pointeur vers une structure de WDF_MEMORY_DESCRIPTOR allouée à l’appelant qui décrit une mémoire tampon qui sera écrite sur la cible d’E/S. Pour plus d'informations, consultez la section Notes qui suit. Ce paramètre est facultatif et peut être NULL si la demande n’envoie pas de données.

[in, optional] OutputBuffer

Pointeur vers une structure de WDF_MEMORY_DESCRIPTOR allouée par l’appelant qui décrit une mémoire tampon qui recevra les données de la cible d’E/S. Pour plus d'informations, consultez la section Notes qui suit. Ce paramètre est facultatif et peut être NULL si la demande ne reçoit pas de données.

[in, optional] RequestOptions

Pointeur vers une structure de WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie les options de la demande. Ce pointeur est facultatif et peut avoir la valeur NULL. Pour plus d'informations, consultez la section Notes qui suit.

[out, optional] BytesReturned

Pointeur vers un emplacement qui reçoit des informations (telles que le nombre d’octets transférés) qu’un autre pilote fournit lorsqu’il termine la demande en appelant WdfRequestCompleteWithInformation. Ce pointeur est facultatif et peut avoir la valeur NULL.

Valeur retournée

Si l’opération réussit, WdfIoTargetSendInternalIoctlSynchronously retourne une fois la demande de contrôle d’appareil interne terminée, et la valeur de retour correspond à la valeur d’achèvement de la requête status. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_REQUEST_SEND_OPTIONS pointée par le paramètre RequestOptions était incorrecte.
STATUS_INVALID_DEVICE_REQUEST	La demande était déjà mise en file d’attente vers une cible d’E/S.
STATUS_INSUFFICIENT_RESOURCES	L’infrastructure n’a pas pu allouer de ressources système (généralement de la mémoire).
STATUS_IO_TIMEOUT	Le pilote a fourni une valeur de délai d’attente et la demande n’a pas été effectuée dans le délai imparti.
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de demande d’E/S (IRP) que représente le paramètre Request ne fournit pas suffisamment de structures IO_STACK_LOCATION pour permettre au pilote de transférer la requête.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Utilisez la méthode WdfIoTargetSendInternalIoctlSynchronously pour envoyer des demandes de contrôle d’appareil internes de manière synchrone. Pour envoyer des demandes de contrôle d’appareil interne de manière asynchrone, utilisez la méthode WdfIotargetFormatRequestForInternalIoctl , suivie de la méthode WdfRequestSend .

Pour plus d’informations sur les demandes de contrôle d’appareil internes, consultez Utilisation de codes de contrôle d’E/S.

La méthode WdfIoTargetSendInternalIoctlSynchronously ne retourne pas tant que la demande n’est pas terminée, sauf si le pilote fournit une valeur de délai d’attente dans la structure WDF_REQUEST_SEND_OPTIONS du paramètre RequestOptions ou si une erreur est détectée.

Vous pouvez transférer une demande de contrôle d’appareil interne que votre pilote a reçue dans une file d’E/S, ou vous pouvez créer et envoyer une nouvelle demande. Dans les deux cas, l’infrastructure nécessite un objet de requête et un espace de mémoire tampon.

Pour transférer une demande de contrôle d’appareil interne que votre pilote a reçue dans une file d’E/S :

Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfIoTargetSendInternalIoctlSynchronously.
Utilisez la mémoire tampon d’entrée de la demande reçue pour le paramètre InputBuffer de la méthode WdfIoTargetSendInternalIoctlSynchronously.
Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle dans la mémoire tampon d’entrée de la requête. Le pilote doit ensuite placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR que le pilote fournit pour le paramètre InputBuffer .
Utilisez la mémoire tampon de sortie de la requête reçue pour le paramètre OutputBuffer de la méthode WdfIoTargetSendInternalIoctlSynchronously.
Le pilote doit appeler WdfRequestRetrieveOutputMemory pour obtenir un handle dans la mémoire tampon de sortie de la requête, puis il doit placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR que le pilote fournit pour le paramètre OutputBuffer .

Pour plus d’informations sur le transfert d’une demande d’E/S, consultez Transfert de demandes d’E/S.

Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’ils envoient à une cible d’E/S, afin que votre pilote puisse en créer de nouvelles.

Pour créer une demande d’E/S :

Fournissez un handle de requête NULL pour le paramètre Request de la méthode WdfIoTargetSendInternalIoctlSynchronously, ou créez un objet de requête et fournissez son handle :
- Si vous fournissez un handle de requête NULL , l’infrastructure utilise un objet de requête interne. Cette technique est simple à utiliser, mais le pilote ne peut pas annuler la demande.
- Si vous appelez WdfRequestCreate pour créer un ou plusieurs objets de requête, vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. Cette technique permet à la fonction de rappel EvtDriverDeviceAdd de votre pilote de préallouer des objets de requête pour un appareil. En outre, un autre thread de pilote peut appeler WdfRequestCancelSentRequest pour annuler la demande, si nécessaire.
Votre pilote peut spécifier un paramètre RequestOptions non NULL, que le pilote fournisse un paramètre de requête non NULL ou NULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.
Fournissez de l’espace tampon pour les paramètres InputBuffer et OutputBuffer de la méthode WdfIogetSendInternalIoctlSynchronously, si la demande les requiert.
Votre pilote peut spécifier cet espace de mémoire tampon en tant que tampons alloués localement, en tant que handles WDFMEMORY ou en tant que listes de descripteurs de mémoire (MDL). Vous pouvez utiliser la méthode la plus pratique.

Si nécessaire, l’infrastructure convertit les descriptions de mémoire tampon afin qu’elles soient correctes pour le type de transfert du IOCTL. Pour plus d’informations sur les types de transfert IOCTL, consultez Définition des codes de contrôle d’E/S.

Les techniques suivantes pour spécifier l’espace tampon sont disponibles :
- Fournissez des mémoires tampons locales.
  Étant donné que WdfIoTargetSendInternalIoctlSynchronously gère de manière synchrone les demandes d’E/S, le pilote peut créer des mémoires tampons de requête qui sont locales pour la routine appelante, comme le montre l’exemple de code suivant.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- Fournissez des handles WDFMEMORY.
  Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour obtenir un handle pour la mémoire gérée par l’infrastructure, comme le montre l’exemple de code suivant.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
```
  Le pilote peut également appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle à un objet de mémoire framework qui représente la mémoire tampon d’une demande d’E/S reçue, si vous souhaitez que le pilote transmette le contenu de cette mémoire tampon à la cible d’E/S. Le pilote ne doit pas terminer la demande d’E/S reçue tant que la nouvelle demande envoyée par WdfIoTargetSendInternalIoctlSynchronously à la cible d’E/S n’a pas été supprimée, réutilisée ou reformatée. (WdfIoTargetSendInternalIoctlSynchronously incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou le reformatage d’un objet de requête décrémente le nombre de références de l’objet mémoire.)
- Fournissez des dll mdl.
  Les pilotes peuvent obtenir des LDM associées à une demande d’E/S reçue en appelant WdfRequestRetrieveInputWdmMdl et WdfRequestRetrieveOutputWdmMdl.

Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur WdfIoTargetSendInternalIoctlSynchronously, consultez Envoi de demandes d’E/S à des cibles d’E/S générales.

Pour plus d’informations sur les cibles d’E/S, consultez Utilisation des cibles d’E/S.

Exemples

L’exemple de code suivant définit une mémoire tampon locale, initialise une structure WDF_MEMORY_DESCRIPTOR et appelle WdfIoTargetSendInternalIoctlSynchronously. Cet exemple spécifie la valeur NULL pour le handle de l’objet de requête, de sorte que l’infrastructure crée un objet de requête pour la cible d’E/S.

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
MY_DRIVER_INFORMATION  driverInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &driverInformation,
                                  sizeof(MY_DRIVER_INFORMATION)
                                  );

status = WdfIoTargetSendInternalIoctlSynchronously(
                                                   hidTarget,
                                                   NULL,
                                                   IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
                                                   NULL,
                                                   &outputDescriptor,
                                                   NULL,
                                                   NULL
                                                   );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfiotarget.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)