USBD_CreateHandle-Funktion (usbdlib.h)

Artikel
08/07/2023

Die USBD_CreateHandle Routine wird von einem WDM-USB-Clienttreiber aufgerufen, um ein USBD-Handle abzurufen. Die Routine registriert den Clienttreiber beim zugrunde liegenden USB-Treiberstapel.

Hinweis für WDF-Treiber (Windows Driver Framework): Wenn Ihr Clienttreiber ein WDF-basierter Treiber ist, benötigen Sie das USBD-Handle nicht. Der Clienttreiber wird in seinem Aufruf der WdfUsbTargetDeviceCreateWithParameters-Methode registriert.

Syntax

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

Parameter

[in] DeviceObject

Zeiger auf das Geräteobjekt für den Clienttreiber.

[in] TargetDeviceObject

Zeiger auf das nächstniedrigere Geräteobjekt im Gerätestapel. Der Clienttreiber empfängt einen Zeiger auf dieses Geräteobjekt in einem vorherigen Aufruf von IoAttachDeviceToDeviceStack.

[in] USBDClientContractVersion

Die vom Clienttreiber unterstützte Vertragsversion. USBDClientContractVersion muss USBD_CLIENT_CONTRACT_VERSION_602 sein. Weitere Informationen finden Sie in den Hinweisen.

[in] PoolTag

Das Pooltag, das für Speicherzuordnungen verwendet wird.

[out] USBDHandle

Undurchsichtiges Handle, das angibt, dass der Clienttreiber beim USB-Treiberstapel registriert wurde. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Die Routine gibt einen NTSTATUS-Code zurück. Mögliche Werte sind unter anderem diese Werte in der folgenden Tabelle.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Routineaufruf war erfolgreich.
STATUS_INVALID_LEVEL	Der Aufrufer wird nicht mit dem IRQL-Wert PASSIVE_LEVEL ausgeführt.
STATUS_INVALID_PARAMETER	Der Aufrufer hat einen der folgenden ungültigen Parameterwerte übergeben: DeviceObject, TargetDeviceObject oder USBDHandle ist NULL. Der in USBDClientContractVersion angegebene Clientvertragswert ist ungültig. PoolTag ist 0.

Hinweise

Versionsregistrierung

Windows 8 enthält einen neuen USB-Treiberstapel zur Unterstützung von USB 3.0-Geräten. Der neue USB-Treiberstapel bietet mehrere neue Funktionen, z. B. Streamunterstützung, verkettete MDLs usw. Bevor Ihr Clienttreiber eine dieser USB-Funktionen verwenden kann, müssen Sie den Clienttreiber beim USB-Treiberstapel registrieren und ein USBD-Handle abrufen. Das Handle ist erforderlich, um Routinen aufzurufen, die die neuen Funktionen verwenden oder konfigurieren. Um ein USBD-Handle zu erhalten, rufen Sie USBD_CreateHandle auf.

Der Clienttreiber muss USBD_CreateHandle aufrufen, unabhängig davon, ob das Gerät an einen USB 3.0-, 2.0- oder 1.1-Hostcontroller angeschlossen ist. Wenn das Gerät an einen USB 3.0-Hostcontroller angeschlossen ist, lädt Windows den USB 3.0-Treiberstapel. Andernfalls wird der USB 2.0-Treiberstapel geladen. In beiden Fällen muss der Clienttreiber die vom zugrunde liegenden USB-Treiberstapel unterstützte Version nicht kennen. USBD_CreateHandle bewertet die Treiberstapelversion und ordnet Ressourcen entsprechend zu.

Der Clienttreiber muss USBD_CLIENT_CONTRACT_VERSION_602 im Parameter USBDClientContractVersion angeben und den Unter Best Practices: Using URBs beschriebenen Regelsatz befolgen.

Aufrufen USBD_CreateHandle

Die USBD_CreateHandle Routine muss von einem WDM-Clienttreiber (Windows Driver Model) aufgerufen werden, bevor der Treiber andere Anforderungen über URBs oder IOCTLs an den USB-Treiberstapel sendet. In der Regel ruft der Clienttreiber das USBD-Handle in seiner AddDevice-Routine ab.

Ein WDF-Clienttreiber (Windows Driver Frameworks) ist nicht erforderlich, um USBD_CreateHandle aufzurufen, da das Framework diese Routine im Namen des Clienttreibers während der Geräteinitialisierungsphase aufruft. Stattdessen kann der Clienttreiber seine Clientvertragsversion in der WDF_USB_DEVICE_CREATE_CONFIG-Struktur angeben und sie im Aufruf von WdfUsbTargetDeviceCreateWithParameters übergeben.

USBD_CreateHandle Anruferfüllung

Wenn der USBD_CreateHandle Aufruf erfolgreich ist, wird ein gültiges USBD-Handle im USBDHandle-Parameter abgerufen. Der Clienttreiber muss das USBD-Handle in den zukünftigen Anforderungen des Clienttreibers an den USB-Treiberstapel verwenden.

Wenn der USBD_CreateHandle Aufrufs fehlschlägt, kann der Clienttreiber die AddDevice-Routine fehlschlagen.

Nachdem der Clienttreiber das USBD-Handle verwendet hat, muss der Treiber das Handle schließen, indem er die USBD_CloseHandle Routine aufruft.

Beispiele

Der folgende Beispielcode zeigt, wie Sie einen Clienttreiber registrieren, indem Sie USBD_CreateHandle aufrufen.

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;
    } 

    ...

}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab.
Zielplattform	Desktop
Kopfzeile	usbdlib.h (include usbdlib.h, usb.h)
Bibliothek	Usbdex.lib; Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

Weitere Informationen

Zuweisung und Erstellen von URBs

Bewährte Methoden: Verwenden von URBs

USBD_CloseHandle

Freigeben über