WdfUsbTargetDeviceCreateWithParameters-Funktion (wdfusb.h)

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceCreateWithParameters-Methode erstellt ein FRAMEWORK-USB-Geräteobjekt für ein angegebenes Frameworkgeräteobjekt und öffnet das USB-Gerät für E/A-Vorgänge. Die -Methode gibt auch 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 für ein 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 Config-Parameter ist nicht die richtige Größe.
STATUS_INSUFFICIENT_RESOURCES
Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues Framework-USB-Geräteobjekt zu erstellen.
STATUS_INVALID_PARAMETER
Ein ungültiger Parameter wurde erkannt. Weitere Informationen finden Sie im Abschnitt Hinweise.
STATUS_UNSUCCESSFUL
Fehler beim Abrufen von USB-Konfigurationsinformationen.
 

Eine Liste mit anderen Rückgabewerten, die von der WdfUsbTargetDeviceCreateWithParameters-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

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 bei 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 auf 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 WdfUsbTargetDeviceCreateWithParameters auch aus einer EvtDriverDeviceAdd-Rückruffunktion aufrufen.

Informationen zur Interaktion von WDM-USB-Clienttreibern mit dem USB 3.0-Treiberstapel 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 URBs nur durch Aufrufen von WdfUsbTargetDeviceCreateUrb oder WdfUsbTargetDeviceCreateIsochUrb erstellen.

Wenn Sie diese Methode aus einem UMDF-Treiber aufrufen, müssen Sie die UmdfDispatcher-Direktive in der INF-Datei des Treibers angeben. Andernfalls gibt diese Methode möglicherweise STATUS_INVALID_PARAMETER zurück. 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 WdfUsbTargetDeviceCreateWithParameters aufruft. Im Beispiel wird das Handle für das FRAMEWORK-USB-Geräteobjekt im vom Treiber definierten Kontextraum 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 Universell
KMDF-Mindestversion 1.11
UMDF-Mindestversion 2.0
Kopfzeile wdfusb.h (wdfusb.h einschließen)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

Weitere Informationen

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreate