fonction USBD_CreateHandle (usbdlib.h)

Article
02/07/2025

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 du handle 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 de périphérique pour le pilote client.

[in] TargetDeviceObject

Pointeur vers l’objet 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 vers 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 Remarques.

[in] PoolTag

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

[out] USBDHandle

Handle opaque qui indique que le pilote client a été inscrit auprès de la pile de pilotes USB. Pour plus d’informations, consultez Remarques.

Valeur de retour

La routine retourne un code NTSTATUS. Les valeurs possibles incluent, mais ne sont pas limitées, ces valeurs dans le tableau suivant.

Retourner le code	Description
STATUS_SUCCESS	L’appel de routine a réussi.
STATUS_INVALID_LEVEL	L’appelant n’est pas en cours d’exécution à 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 est NULL. 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 appareils USB 3.0. La nouvelle pile de pilotes USB offre plusieurs nouvelles fonctionnalités, telles que la prise en charge des flux, les MDL chaînés, 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 requis pour connaître la version prise en charge par la pile de pilotes USB sous-jacente. USBD_CreateHandle évalue la version de la pile des 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 des URI.

USBD_CreateHandle d’appel

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, par le biais d’URL ou de IOCTLs, à la pile des 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 l’infrastructure appelle cette routine pour le compte 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 le transmettre à 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 requêtes futures du pilote client sur la pile de pilotes USB.

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

Une fois le pilote client terminé à l’aide du handle 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;
    } 

    ...

}

Exigences

Exigence	Valeur
client minimum 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	Bureau
d’en-tête	usbdlib.h (include 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