fonction USBD_CreateHandle (usbdlib.h)

Article
02/27/2024

La routine USBD_CreateHandle est appelée par un pilote client USB WDM pour obtenir un handle USBD. La routine inscrit le pilote client avec la pile de pilotes USB sous-jacente.

Remarque pour les pilotes WDF (Windows Driver Framework) : Si votre pilote client est un pilote WDF, vous n’avez pas besoin de la poignée USBD. Le pilote client est inscrit dans son appel à la méthode WdfUsbTargetDeviceCreateWithParameters .

Syntaxe

NTSTATUS USBD_CreateHandle(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  PDEVICE_OBJECT TargetDeviceObject,
  [in]  ULONG          USBDClientContractVersion,
  [in]  ULONG          PoolTag,
  [out] USBD_HANDLE    *USBDHandle
);

Paramètres

[in] DeviceObject

Pointeur vers l’objet d’appareil pour le pilote client.

[in] TargetDeviceObject

Pointeur vers l’objet d’appareil inférieur suivant dans la pile d’appareils. Le pilote client reçoit un pointeur vers cet objet d’appareil dans un appel précédent à IoAttachDeviceToDeviceStack.

[in] USBDClientContractVersion

Version de contrat prise en charge par le pilote client. USBDClientContractVersion doit être USBD_CLIENT_CONTRACT_VERSION_602. Pour plus d'informations, consultez la section Notes.

[in] PoolTag

Balise de pool utilisée pour les allocations de mémoire.

[out] USBDHandle

Poignée opaque qui indique que le pilote client a été inscrit auprès de la pile de pilotes USB. Pour plus d'informations, consultez la section Notes.

Valeur retournée

La routine retourne un code NTSTATUS. Les valeurs possibles incluent, sans s’y limiter, ces valeurs dans le tableau suivant.

Code de retour	Description
STATUS_SUCCESS	L’appel de routine a réussi.
STATUS_INVALID_LEVEL	L’appelant ne s’exécute pas à la valeur IRQL PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	L’appelant a passé l’une des valeurs de paramètre non valides suivantes : DeviceObject, TargetDeviceObject ou USBDHandle a la valeur NULL. La valeur du contrat client spécifiée dans USBDClientContractVersion n’est pas valide. PoolTag est égal à zéro.

Remarques

Inscription de version

Windows 8 inclut une nouvelle pile de pilotes USB pour prendre en charge les périphériques USB 3.0. La nouvelle pile de pilotes USB offre plusieurs nouvelles fonctionnalités, telles que la prise en charge des flux, les dll MDL chaînées, etc. Avant que votre pilote client puisse utiliser l’une de ces fonctionnalités USB, vous devez inscrire le pilote client auprès de la pile de pilotes USB et obtenir une poignée USBD. Le handle est nécessaire pour appeler des routines qui utilisent ou configurent les nouvelles fonctionnalités. Pour obtenir un handle USBD, appelez USBD_CreateHandle.

Le pilote client doit appeler USBD_CreateHandle que l’appareil soit attaché à un contrôleur hôte USB 3.0, 2.0 ou 1.1. Si l’appareil est attaché à un contrôleur hôte USB 3.0, Windows charge la pile de pilotes USB 3.0. Sinon, la pile de pilotes USB 2.0 est chargée. Dans les deux cas, le pilote client n’est pas tenu de connaître la version prise en charge par la pile de pilotes USB sous-jacente. USBD_CreateHandle évalue la version de la pile de pilotes et alloue les ressources de manière appropriée.

Le pilote client doit spécifier USBD_CLIENT_CONTRACT_VERSION_602 dans le paramètre USBDClientContractVersion et suivre l’ensemble de règles décrites dans Meilleures pratiques : utilisation d’URBs.

Appel de USBD_CreateHandle

La routine USBD_CreateHandle doit être appelée par un pilote client WDM (Windows Driver Model) avant que le pilote n’envoie d’autres requêtes, via des URL ou des IOCTL, à la pile de pilotes USB. En règle générale, le pilote client obtient le handle USBD dans sa routine AddDevice.

Un pilote client WDF (Windows Driver Frameworks) n’est pas nécessaire pour appeler USBD_CreateHandle , car le framework appelle cette routine au nom du pilote client pendant la phase d’initialisation de l’appareil. Au lieu de cela, le pilote client peut spécifier sa version de contrat client dans la structure WDF_USB_DEVICE_CREATE_CONFIG et la passer à l’appel à WdfUsbTargetDeviceCreateWithParameters.

USBD_CreateHandle fin de l’appel

Si l’appel USBD_CreateHandle réussit, un handle USBD valide est obtenu dans le paramètre USBDHandle . Le pilote client doit utiliser le handle USBD dans les futures demandes du pilote client à la pile de pilotes USB.

Si l’appel USBD_CreateHandle échoue, le pilote client peut échouer dans la routine AddDevice.

Une fois que le pilote client a terminé d’utiliser la poignée USBD, le pilote doit fermer le handle en appelant la routine USBD_CloseHandle .

Exemples

L’exemple de code suivant montre comment inscrire un pilote client en appelant USBD_CreateHandle.

DRIVER_ADD_DEVICE MyAddDevice;

NTSTATUS MyAddDevice( __in PDRIVER_OBJECT  DriverObject,
                     __in PDEVICE_OBJECT  PhysicalDeviceObject)
{

    NTSTATUS            ntStatus;
    PDEVICE_OBJECT      deviceObject;
    PDEVICE_EXTENSION   deviceExtension;
    PDEVICE_OBJECT      stackDeviceObject;
    USBD_HANDLE         usbdHandle;

    ...

        ntStatus = IoCreateDevice(DriverObject,
        sizeof(DEVICE_EXTENSION),
        NULL,
        FILE_DEVICE_UNKNOWN,
        FILE_AUTOGENERATED_DEVICE_NAME,
        FALSE,
        &deviceObject);


    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        //     Attach the FDO to the top of the PDO in the client driver's 
        //  device stack.

        deviceExtension->StackDeviceObject = IoAttachDeviceToDeviceStack (
        deviceObject,
        PhysicalDeviceObject);

    ...

        // Initialize the DeviceExtension

        deviceExtension = deviceObject->DeviceExtension;

    ...

        //Register the client driver with the USB driver stack.
        //Obtain a USBD handle for registration.

        ntStatus = USBD_CreateHandle(deviceObject, 
        deviceExtension->StackDeviceObject,
        USBD_CLIENT_CONTRACT_VERSION_602,
        POOL_TAG,
        &deviceExtension->USBDHandle);

    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        // Call USBD_QueryUsbCapability to determine 
        // stream support. 

        ntStatus = USBD_QueryUsbCapability ( deviceExtension->USBDHandle,  
        (GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,  
        sizeof(ULONG),  
        (PUCHAR) &deviceExtension.MaxSupportedStreams);  


    if (!NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->MaxSupportedStreams = 0;
        ntStatus = STATUS_SUCCESS;
    } 

    ...

}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Nécessite WDK pour Windows 8. Cible Windows Vista et les versions ultérieures du système d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	usbdlib.h (inclure usbdlib.h, usb.h)
Bibliothèque	Usbdex.lib ; Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

Voir aussi

Allocation et génération d’URBs

Meilleures pratiques : Utilisation d’URBs

USBD_CloseHandle

Partager via