WdfUsbTargetDeviceCreate-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

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

Hinweis Wenn Sie Ihren Treiber mithilfe von KMDF 1.11 oder UMDF 2.0 oder höher erstellen, empfehlen wir, WdfUsbTargetDeviceCreateWithParameters anstelle von WdfUsbTargetDeviceCreateaufzurufen.

Syntax

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

Parameter

[in] Device

Ein Handle zu einem 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 Versuch, USB-Konfigurationsinformationen abzurufen.

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

Ein Treiber, der ein USB-E/A-Ziel verwendet, muss WdfUsbTargetDeviceCreate aufrufen, nachdem sein Gerät in den Arbeitszustand (D0) wechselt. In der Regel ruft ein Treiber WdfUsbTargetDeviceCreate innerhalb der EvtDevicePrepareHardware Rückruffunktion auf. (Der Treiber kann WdfUsbTargetDeviceCreate nicht innerhalb der 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 von der Konfiguration unterstützten Schnittstellen zu ermitteln, kann der Treiber WdfUsbTargetDeviceGetNumInterfacesaufrufen.

Nach dem Aufrufen WdfUsbTargetDeviceCreatekann Ihr Treiber zusätzliche Framework-USB-Geräteobjektmethodenaufrufen.

Das übergeordnete Element jedes USB-Geräteobjekts ist das Framework-Treiberobjekt 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 WdfUsbTargetDeviceCreateaufruft. Im Beispiel wird das Handle des USB-Geräteobjekts im vom Treiber definierten Kontextbereich 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-	Universal
Minimale KMDF-Version	1.0
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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDevic, UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Siehe auch

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces

Freigeben über