WdfIoTargetSendInternalIoctlOthersSynchronously, fonction (wdfiotarget.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfIoTargetSendInternalIoctlOthersSynchronously génère une demande de contrôle d’appareil interne non standard et l’envoie de façon synchrone à une cible d’E/S.

Syntaxe

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [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] OtherArg1

Pointeur vers une structure de WDF_MEMORY_DESCRIPTOR qui décrit une mémoire tampon qui contient des informations de contexte. Ce paramètre est facultatif et peut être NULL.

[in, optional] OtherArg2

Pointeur vers une structure WDF_MEMORY_DESCRIPTOR qui décrit une mémoire tampon qui contient des informations de contexte. Ce paramètre est facultatif et peut être NULL.

[in, optional] OtherArg4

Pointeur vers une structure WDF_MEMORY_DESCRIPTOR qui décrit une mémoire tampon qui contient des informations de contexte. Ce paramètre est facultatif et peut être NULL.

[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, WdfIoTargetSendInternalIoctlOthersSynchronous retourne une fois la demande de contrôle d’appareil interne 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
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 requête a déjà été 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 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

Une demande de contrôle d’appareil interne non standard utilise un code IOCTL pour identifier l’opération à effectuer, mais la demande n’utilise pas les mémoires tampons d’entrée et de sortie standard utilisées par d’autres demandes de contrôle d’appareil interne. Si vous créez un ensemble de pilotes en interaction, vous pouvez définir comment cet ensemble de pilotes utilise les arguments de la requête : OtherArg1, OtherArg2 et OtherArg4.

Il n’existe aucun paramètre appelé OtherArg3 , car le framework associe ces paramètres aux membres Argument1, Argument2 et Argument4 de l’union Other.Parameters dans la structure IO_STACK_LOCATION du pilote. Le membre Argument3 de cette union reçoit la valeur du paramètre IoctlCode . Elle n’est donc pas disponible pour les autres valeurs fournies par le pilote.

Utilisez la méthode WdfIoTargetSendInternalIoctlOthersSynchronously pour envoyer des demandes de contrôle d’appareil interne non standard de manière synchrone. Pour envoyer des demandes de contrôle d’appareil interne de manière asynchrone, utilisez WdfIoTargetFormatRequestForInternalIoctlOthers, suivi de WdfRequestSend.

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

La méthode WdfIoTargetSendInternalIoctlOthersSynchronously ne retourne pas la requête 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 si une erreur est détectée.

Vous pouvez transférer une demande de contrôle d’appareil interne non standard 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 éventuellement un espace de contexte.

Pour transférer une demande de contrôle d’appareil interne non standard 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 WdfIoTargetSendInternalIoctlOthersSynchronously.
Utilisez les informations de contexte de la requête reçue pour les paramètres OtherArg1,OtherArg2 etOtherArg4 de la méthode WdfIoTargetSendInternalIoctlOthersSynchronously.
Pour obtenir ces valeurs de paramètres, le pilote doit appeler WdfRequestGetParameters et utiliser le membre DeviceIoControl de la structure WDF_REQUEST_PARAMETERS qui est retournée.

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, 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 WdfIoTargetSendInternalIoctlOthersSynchronously, 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 contexte pour les paramètres OtherArg1,OtherArg2 et OtherArg4 de la méthode WdfIoTargetSendInternalIoctlOthersSynchronously, si la requête les requiert.
Votre pilote peut spécifier cet espace de contexte 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.

Les techniques suivantes pour spécifier l’espace de mémoire tampon sont disponibles :
- Fournissez des mémoires tampons locales.
  Étant donné que WdfIoTargetSendInternalIoctlOthersSynchronousSynchronously 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 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 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);
```
- Fournissez des DLL.
  Les pilotes peuvent obtenir des DLL 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 d’informations d’achèvement.

Pour plus d’informations sur WdfIoTargetSendInternalIoctlOthersSynchronous, 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 initialise une structure IEEE 1394 IRB, utilise l’adresse de la structure pour initialiser une structure WDF_MEMORY_DESCRIPTOR , puis appelle WdfIoTargetSendInternalIoctlOthersSynchronous.

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           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 des versions 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)