USBD_CreateHandle-Funktion (usbdlib.h)

Artikel
02/07/2025

Die USBD_CreateHandle Routine wird von einem WDM-USB-Clienttreiber aufgerufen, um einen USBD-Handle zu erhalten. Die Routine registriert den Clienttreiber mit dem zugrunde liegenden USB-Treiberstapel.

Hinweis für Windows Driver Framework (WDF)-Treiber: Wenn ihr Clienttreiber ein WDF-basierter Treiber ist, benötigen Sie das USBD-Handle nicht. Der Clienttreiber wird im 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

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

[in] USBDClientContractVersion

Die Vertragsversion, die der Clienttreiber unterstützt. USBDClientContractVersion- muss USBD_CLIENT_CONTRACT_VERSION_602 sein. Weitere Informationen finden Sie in den Hinweisen.

[in] PoolTag

Das Pooltag, das für Speicherzuweisungen 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 jedoch nicht beschränkt auf diese Werte in der folgenden Tabelle.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Routineaufruf war erfolgreich.
STATUS_INVALID_LEVEL	Der Aufrufer wird nicht am 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 Null.

Bemerkungen

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 einen USBD-Handle erhalten. Das Handle ist erforderlich, um Routinen aufzurufen, die die neuen Funktionen verwenden oder konfigurieren. Rufen Sie USBD_CreateHandleauf, um einen USBD-Handle zu erhalten.

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 ist der Clienttreiber nicht erforderlich, um die vom zugrunde liegenden USB-Treiberstapel unterstützte Version zu kennen. USBD_CreateHandle bewertet die Treiberstapelversion und weist Ressourcen entsprechend zu.

Der Clienttreiber muss USBD_CLIENT_CONTRACT_VERSION_602 im USBDClientContractVersion Parameter angeben und die in Best Practices beschriebenen Regeln befolgen: Verwenden von URBs.

Anruf USBD_CreateHandle

Die USBD_CreateHandle Routine muss von einem Windows Driver Model (WDM)-Clienttreiber 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 Windows Driver Frameworks (WDF)-Clienttreiber ist nicht erforderlich, um USBD_CreateHandle aufzurufen, da das Framework diese Routine während der Geräteinitialisierungsphase im Namen des Clienttreibers aufruft. Stattdessen kann der Clienttreiber seine Clientvertragsversion in der WDF_USB_DEVICE_CREATE_CONFIG-Struktur angeben und im Aufruf von WdfUsbTargetDeviceCreateWithParametersübergeben.

USBD_CreateHandle Anrufabschluss

Wenn der USBD_CreateHandle Aufruf erfolgreich ist, wird ein gültiger 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 Aufruf fehlschlägt, kann der Clienttreiber die AddDevice-Routine nicht ausführen.

Nachdem der Clienttreiber mit dem USBD-Handle fertig ist, muss der Treiber das Handle schließen, indem er die USBD_CloseHandle Routine aufruft.

Beispiele

Im folgenden Beispielcode wird gezeigt, wie Ein Clienttreiber durch Aufrufen von USBD_CreateHandleregistriert wird.

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
mindestens unterstützte Client-	Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab.
Zielplattform-	Desktop
Header-	usbdlib.h (enthalten usbdlib.h, usb.h)
Library	Usbdex.lib; Ntstrsafe.lib
IRQL-	PASSIVE_LEVEL

Siehe auch

Zuweisung und Erstellen von URBs

bewährte Methoden: Verwenden von URBs

USBD_CloseHandle

Freigeben über