WdfIoTargetSendIoctlSynchronously, fonction (wdfiotarget.h)

Article
07/16/2024

[S’applique à KMDF et UMDF]

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

Syntaxe

NTSTATUS WdfIoTargetSendIoctlSynchronously(
  [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 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 vers un objet de requête de framework. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[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 WDF_MEMORY_DESCRIPTOR allouée par l’appelant qui décrit une mémoire tampon qui sera écrite dans la cible d’E/S. Pour plus d’informations, consultez la section Remarques suivante. 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 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 Remarques suivante. Ce paramètre est facultatif et peut être NULL si la requête ne reçoit pas de données.

[in, optional] RequestOptions

Pointeur vers une structure WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie les options de la requête. Ce pointeur est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[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 requête en appelant WdfRequestCompleteWithInformation. Ce pointeur est facultatif et peut être NULL.

Valeur de retour

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

Retourner le code	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 vers laquelle le paramètre RequestOptions pointait de façon incorrecte.
STATUS_INVALID_DEVICE_REQUEST	La requête a déjà été mise en file d’attente vers une cible d’E/S.
STATUS_INSUFFICIENT_RESOURCES	L’infrastructure ne peut pas allouer de ressources système (généralement la mémoire).
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de requête d’E/S (IRP) que le paramètre Request représente 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 .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

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

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

La méthode WdfIoTargetSendIoctlSynchronously ne retourne pas tant que la requête 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 à moins qu’une erreur ne soit détectée.

Vous pouvez transférer une demande de contrôle d’appareil reçue par votre pilote dans une file d’attente 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 tampon.

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

Spécifiez le handle de la requête reçue pour le paramètre Request Request WdfIoTargetSendIoctlSynchronously.
Utilisez la mémoire tampon d’entrée de la requête reçue pour le paramètre WdfIoTargetSendIoctlSynchronously méthode InputBuffer.
Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle vers un objet de mémoire du framework qui représente la mémoire tampon d’entrée de la requête. Ensuite, le pilote doit placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR que le pilote fournit pour le paramètre InputBuffer de WdfIoTargetSendIoctlSynchronously.
Utilisez la mémoire tampon de sortie de la requête reçue pour le paramètre WdfIoTargetSendIoctlSynchronouslyOutputBuffer.
Le pilote doit appeler WdfRequestRetrieveOutputMemory pour obtenir un handle vers un objet mémoire du framework qui représente la mémoire tampon de sortie de la requête. Ensuite, le pilote doit placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR que le pilote fournit pour le paramètre OutputBuffer de WdfIoTargetSendIoctlSynchronously.

Pour plus d’informations sur le transfert d’une requête d’E/S, consultez demandes d’E/S de transfert.

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 créer de nouvelles requêtes.

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

Fournissez un handle de requête NULL
pour le paramètre Request de la méthode WdfIoTargetSendIoctlSynchronous ly, 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 aux EvtDriverDeviceAdd fonction de rappel de préallouer les objets de requête d’un appareil. En outre, un autre thread de pilote peut appeler WdfRequestCancelSentRequest pour annuler la requête, si nécessaire.
Votre pilote peut spécifier un paramètre RequestOptions nonNULL ou une NULLDemander paramètre. 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 la méthode WdfIoTargetSendIoctlSynchronously méthode InputBuffer et paramètres OutputBuffer, si la requête les requiert.
Votre pilote peut spécifier cet espace tampon en tant que mémoires tampons allouées 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, le framework 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 WdfIoTargetSendIoctlSynchronously gère les requêtes d’E/S de manière synchrone, le pilote peut créer des mémoires tampons de requête locales à la routine appelante, comme l’illustre 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 de mémoire gérée par l’infrastructure, comme l’illustre 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);
```
  Sinon, le pilote peut appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle à un objet mémoire de framework qui représente la mémoire tampon d’une requête d’E/S reçue, si vous souhaitez que le pilote passe 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 requête WdfIoTargetSendIoctlSynchronously envoyées à la cible d’E/S a été supprimée, réutilisée ou reformatée. (WdfIoTargetSendIoctlSynchronously incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou la reformatage d’un objet de requête décrémente le nombre de références de l’objet mémoire.)
- Fournissez des DLL.
  Les pilotes peuvent obtenir des DLL associées à une requête d’E/S reçue en appelant WdfRequestRetrieveInputWdmMdl et WdfRequestRetrieveOutputWdmMdl.

Pour plus d’informations sur l’obtention des informations d’état une fois qu’une demande d’E/S est terminée, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur WdfIoTargetSendIoctlSynchronously, consultez Envoi de requêtes 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 WdfIoTargetSendIoctlSynchronously. Cet exemple spécifie NULL pour le handle d’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;
HID_COLLECTION_INFORMATION  collectionInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &collectionInformation,
                                  sizeof(HID_COLLECTION_INFORMATION)
                                  );

status = WdfIoTargetSendIoctlSynchronously(
                                           hidTarget,
                                           NULL,
                                           IOCTL_HID_GET_COLLECTION_INFORMATION,
                                           NULL,
                                           &outputDescriptor,
                                           NULL,
                                           NULL
                                           );

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfiotarget.h (include Wdf.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf)