WdfUsbTargetDeviceFormatRequestForUrb, fonction (wdfusb.h)

[S’applique uniquement à KMDF]

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 d’un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

[in] UrbMemory

Handle d’un objet de mémoire 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 contenue 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 à l’appelant qui fournit des valeurs facultatives de décalage d’octet 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 :

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 demande 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 demande 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), reformater (appeler WdfUsbTargetDeviceFormatRequestForUrb) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une STATUS_INSUFFICIENT_RESOURCES valeur de retour à partir 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 de paramètre ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme des requêtes à 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 des 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

Voir aussi

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfRequestReuse

WdfRequestSend

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceSendUrbSynchronously