WdfIoTargetSendIoctlSynchronously, fonction (wdfiotarget.h)
[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 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 pour 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 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 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 à l’appelant qui décrit une mémoire tampon qui recevra des 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 des options pour la demande. Ce pointeur est facultatif et peut être 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 être NULL.
Valeur retournée
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’achèvement de la requête status. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
Code de retour | Description |
---|---|
|
Un paramètre non valide a été détecté. |
|
La taille de la structure WDF_REQUEST_SEND_OPTIONS pointée par le paramètre RequestOptions était incorrecte. |
|
La requête a déjà été mise en file d’attente vers une cible d’E/S. |
|
L’infrastructure ne peut pas allouer de ressources système (généralement de la mémoire). |
|
Le paquet de demandes 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 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 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 que votre pilote a reçue 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 de mémoire tampon.
Pour transférer une demande de contrôle de périphérique que votre pilote a reçue dans une file d’attente d’E/S :
- Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfIoTargetSendIoctlSynchronously.
-
Utilisez la mémoire tampon d’entrée de la requête reçue pour le paramètre InputBuffer de la méthode WdfIoTargetSendIoctlSynchronously.
Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle pour 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 OutputBuffer de la méthode WdfIoTargetSendIoctlSynchronously.
Le pilote doit appeler WdfRequestRetrieveOutputMemory pour obtenir un handle pour un objet de 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.
Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’ils envoient à une cible d’E/S, de sorte que votre pilote peut créer de nouvelles demandes.
Pour créer une demande d’E/S :
-
Fournissez un handle de requête NULL pour le paramètre Request de la méthode WdfIoTargetSendIoctlSynchronously, 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 non NULL ou un paramètre de requêteNULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.
-
Fournissez un espace de mémoire tampon pour les paramètres InputBuffer et OutputBuffer de la méthode WdfIogetSendIoctlSynchronously, si la requête les requiert.
Votre pilote peut spécifier cet espace de mémoire 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, l’infrastructure convertit les descriptions de la mémoire tampon afin qu’elles soient correctes pour le type de transfert de l’IOCTL. Pour plus d’informations sur les types de transfert IOCTL, consultez Définition de codes de contrôle d’E/S.
Les techniques suivantes pour spécifier l’espace de mémoire tampon sont disponibles :
-
Fournissez des mémoires tampons locales.
Étant donné que WdfIoTargetSendIoctlSynchronously gère les demandes d’E/S de manière synchrone, le pilote peut créer des mémoires tampons de requête qui sont locales à 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 les 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 mémoire du framework qui représente la mémoire tampon d’une demande 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 que WdfIoTargetSendIoctlSynchronously envoie à la cible d’E/S n’a pas é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émentent le nombre de références de l’objet mémoire.)
-
Fournissez des DLL.
Les pilotes peuvent obtenir des DLL associées à une demande d’E/S reçue en appelant WdfRequestRetrieveInputWdmMdl et WdfRequestRetrieveOutputWdmMdl.
-
Fournissez des mémoires tampons locales.
Pour plus d’informations sur WdfIoTargetSendIoctlSynchronously, 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 de 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
);
Configuration requise
Condition requise | Valeur |
---|---|
Plateforme cible | Universal |
Version KMDF minimale | 1.0 |
Version UMDF minimale | 2.0 |
En-tête | wdfiotarget.h (inclure 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), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf) |
Voir aussi
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendInternalIoctlSynchronously
WdfRequestCompleteWithInformation
WdfRequestRetrieveOutputMemory
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour