WdfUsbTargetDeviceCreate-Funktion (wdfusb.h)

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceCreate-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.

Hinweis Wenn Sie Ihren Treiber mithilfe von KMDF 1.11 oder UMDF 2.0 oder höher erstellen, empfiehlt es sich, WdfUsbTargetDeviceCreateWithParameters anstelle von WdfUsbTargetDeviceCreate aufzurufen.

 

Syntax

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

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in, optional] Attributes

Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das neue 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

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues USB-Geräteobjekt zu erstellen.
STATUS_UNSUCCESSFUL	Fehler beim Abrufen von USB-Konfigurationsinformationen.

 

Eine Liste mit anderen Rückgabewerten, die von der WdfUsbTargetDeviceCreate-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

Ein Treiber, der ein USB-E/A-Ziel verwendet, muss WdfUsbTargetDeviceCreate aufrufen, nachdem das Gerät in den Arbeitszustand (D0) wechselt. In der Regel ruft ein Treiber WdfUsbTargetDeviceCreate aus seiner EvtDevicePrepareHardware-Rückruffunktion auf. (Der Treiber kann WdfUsbTargetDeviceCreate nicht innerhalb seiner EvtDriverDeviceAdd-Rückruffunktion aufrufen.)

WdfUsbTargetDeviceCreate ruft den USB-Gerätedeskriptor und den ersten USB-Konfigurationsdeskriptor vom Gerät ab und speichert sie. Außerdem wird ein Framework-USB-Schnittstellenobjekt für jede Schnittstelle in der ersten Konfiguration des Geräts erstellt. Um die Anzahl der Schnittstellen zu bestimmen, die die Konfiguration unterstützt, kann der Treiber WdfUsbTargetDeviceGetNumInterfaces aufrufen.

Nach dem Aufrufen von WdfUsbTargetDeviceCreate kann Ihr Treiber zusätzliche Framework-USB-Geräteobjektmethoden aufrufen.

Das übergeordnete Element jedes USB-Geräteobjekts ist das Frameworktreiberobjekt des Treibers. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject-Element oder die WDF_OBJECT_ATTRIBUTES-Struktur muss NULL sein.

Weitere Informationen zur WdfUsbTargetDeviceCreate-Methode und usb-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Das folgende Codebeispiel ist Teil einer EvtDevicePrepareHardware-Rückruffunktion , die WdfUsbTargetDeviceCreate aufruft. Im Beispiel wird das Handle des USB-Geräteobjekts im vom Treiber definierten Kontextraum gespeichert.

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

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Weitere Informationen

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces