WdfUsbTargetDeviceFormatRequestForUrb, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfUsbTargetDeviceFormatRequestForUrb génère une requête USB pour un périphérique USB spécifié, à l’aide des paramètres de requête décrits par un URB, mais elle n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Paramètres

[in] UsbDevice

Handle pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Handle pour un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

[in] UrbMemory

Handle vers un objet de mémoire de framework qui contient une structure URB ou l’un des membres de l’union de la structure. (Tous les membres de l’union de la structure URB contiennent la structure _URB_HEADER .)

Si le pilote a précédemment appelé WdfUsbTargetDeviceCreateWithParameters pour créer UsbDevice, le pilote doit utiliser WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb pour créer l’URB contenu dans cet objet mémoire. Sinon, un bogue case activée se produit.

[in, optional] UrbMemoryOffset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octets et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse de début de l’URB dans la mémoire spécifiée par UrbMemory . Si ce pointeur a la valeur NULL, l’URB se trouve au début de la mémoire UrbMemory .

Valeur retournée

WdfUsbTargetDeviceFormatRequestForUrb retourne STATUS_SUCCESS si l’opération réussit. 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_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.
STATUS_INTEGER_OVERFLOW	Décalage que le paramètre UsbMemoryOffset a spécifié n’est pas valide.

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 WdfUsbTargetDeviceFormatRequestForUrb, suivi de WdfRequestSend, pour envoyer une demande de transfert de contrôle USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetDeviceSendUrbSynchronously pour envoyer une requête de manière synchrone.

Vous pouvez transférer une demande d’E/S que votre pilote a reçue dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande.

Pour transférer une demande d’E/S 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 de la méthode WdfUsbTargetDeviceFormatRequestForUrb.

Pour créer une demande d’E/S, appelez WdfRequestCreate pour préallouer un objet de requête. Fournissez le handle de requête pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForUrb. Vous pouvez réutiliser l’objet de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de requête pour un appareil.

Après avoir appelé WdfUsbTargetDeviceFormatRequestForUrb pour mettre en forme une requête d’E/S, le pilote doit appeler WdfRequestSend pour envoyer la requête (de manière synchrone ou asynchrone) à une cible d’E/S. N’utilisez pas l’option Envoyer et oublier pour envoyer la demande.

Les appels multiples à WdfUsbTargetDeviceFormatRequestForUrb qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut appeler WdfRequestCreate pour préallouer un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformat (appeler WdfUsbTargetDeviceFormatRequestForUrb) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une valeur de retour STATUS_INSUFFICIENT_RESOURCES d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetDeviceFormatRequestForUrb pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs des paramètres ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme de requête à chaque fois, des ressources supplémentaires peuvent être allouées.)

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 la méthode WdfUsbTargetDeviceFormatRequestForUrb et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant crée un objet mémoire pour contenir une structure URB, initialise la structure URB et appelle WdfUsbTargetDeviceFormatRequestForUrb pour mettre en forme une requête qui utilise le contenu de la structure URB. Ensuite, l’exemple inscrit une fonction de rappel CompletionRoutine et envoie la requête à une cible d’E/S.

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)