WdfUsbTargetDeviceCreateWithParameters-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceCreateWithParameters--Methode erstellt ein Framework-USB-Geräteobjekt für ein angegebenes Framework-Geräteobjekt und öffnet das USB-Gerät für E/A-Vorgänge. Die Methode gibt außerdem Konfigurationsinformationen für das Framework-USB-Geräteobjekt an.

Syntax

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Parameter

[in] Device

Ein Handle zu einem Framework-Geräteobjekt.

[in] Config

Ein Zeiger auf eine WDF_USB_DEVICE_CREATE_CONFIG-Struktur, die Konfigurationsinformationen für das FRAMEWORK-USB-Geräteobjekt enthält.

[in, optional] Attributes

Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das neue Framework-USB-Geräteobjekt enthält. (Das ParentObject-Element der Struktur muss NULL sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] UsbDevice

Ein Zeiger auf eine Position, die ein Handle für das neue Framework-USB-Geräteobjekt empfängt.

Rückgabewert

WdfUsbTargetDeviceCreateWithParameters gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INFO_LENGTH_MISMATCH	Der parameter Config ist nicht die richtige Größe.
STATUS_INSUFFICIENT_RESOURCES	Zum Erstellen eines neuen Framework-USB-Geräteobjekts ist nicht genügend Arbeitsspeicher vorhanden.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt. Weitere Informationen finden Sie im Abschnitt "Hinweise".
STATUS_UNSUCCESSFUL	Fehler beim Versuch, USB-Konfigurationsinformationen abzurufen.

Eine Liste mit anderen Rückgabewerten, die von der WdfUsbTargetDeviceCreateWithParameters Methode möglicherweise zurückgegeben werden, finden Sie unter Framework Object Creation Errors.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Windows 8 enthält einen neuen USB-Treiberstapel zur Unterstützung von USB 3.0-Geräten.

Bevor ein frameworkbasierter Clienttreiber die neuen Funktionen des USB-Treiberstapels für Windows 8 verwenden kann, muss sich der Treiber mit dem zugrunde liegenden USB-Treiberstapel registrieren, der von Windows für das Gerät geladen wird. Rufen Sie zum Registrieren des Clienttreibers WdfUsbTargetDeviceCreateWithParameters auf, und geben Sie eine Vertragsversion in der WDF_USB_DEVICE_CREATE_CONFIG-Struktur an.

Wenn der Clienttreiber die Verbesserungen und die neuen Funktionen unter Windows 8 erstellen, ausführen und verwenden soll, wird die Clientvertragsversion USBD_CLIENT_CONTRACT_VERSION_602.

In der Regel rufen Treiber WdfUsbTargetDeviceCreateWithParameters aus einer EvtDevicePrepareHardware- Rückruffunktion auf. Treiber können auch WdfUsbTargetDeviceCreateWithParameters innerhalb einer EvtDriverDeviceAdd- Rückruffunktion aufrufen.

Informationen dazu, wie WDM-USB-Clienttreiber mit dem USB 3.0-Treiberstapel interagieren, finden Sie unter Bewährte Methoden: Verwenden von URBs.

Wenn der Treiber WdfUsbTargetDeviceCreateWithParameters aufruft, um ein Framework-USB-Geräteobjekt zu erstellen, muss der Treiber NUR URBs erstellen, indem WdfUsbTargetDeviceCreateUrb oder WdfUsbTargetDeviceCreateIsochUrbaufgerufen wird.

Wenn Sie diese Methode von einem UMDF-Treiber aufrufen, müssen Sie die UmdfDispatcher--Direktive in der INF-Datei des Treibers angeben. Andernfalls kann diese Methode STATUS_INVALID_PARAMETERzurückgeben. Weitere Informationen zu dieser Direktive finden Sie unter Angeben von WDF-Direktiven in INF-Dateien.

Beispiele

Das folgende Codebeispiel ist Teil einer EvtDevicePrepareHardware- Rückruffunktion, die WdfUsbTargetDeviceCreateWithParametersaufruft. Im Beispiel wird das Handle für das Framework-USB-Geräteobjekt im vom Treiber definierten Kontextbereich gespeichert.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.11
Mindest-UMDF-Version	2.0
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

Siehe auch

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate

Freigeben über