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 |
|---|---|
|
Der Config-Parameter ist nicht die richtige Größe. |
|
Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues Framework-USB-Geräteobjekt zu erstellen. |
|
Ein ungültiger Parameter wurde erkannt. Weitere Informationen finden Sie im Abschnitt Hinweise. |
|
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) |