Funzione WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetDeviceCreateWithParameters crea un oggetto dispositivo USB framework per un oggetto dispositivo framework specificato e apre il dispositivo USB per le operazioni di I/O. Il metodo specifica anche le informazioni di configurazione per l'oggetto dispositivo USB framework.
Sintassi
NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
[in] WDFDEVICE Device,
[in] PWDF_USB_DEVICE_CREATE_CONFIG Config,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFUSBDEVICE *UsbDevice
);
Parametri
[in] Device
Handle per un oggetto dispositivo framework.
[in] Config
Puntatore a una struttura WDF_USB_DEVICE_CREATE_CONFIG che contiene informazioni di configurazione per l'oggetto dispositivo USB framework.
[in, optional] Attributes
Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES fornita dal chiamante che contiene gli attributi per il nuovo oggetto dispositivo USB del framework. Il membro ParentObject della struttura deve essere NULL. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.
[out] UsbDevice
Puntatore a una posizione che riceve un handle per il nuovo oggetto dispositivo USB del framework.
Valore restituito
WdfUsbTargetDeviceCreateWithParameters restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Il parametro config non è la dimensione corretta. |
|
Memoria insufficiente per creare un nuovo oggetto dispositivo USB del framework. |
|
È stato rilevato un parametro non valido. Per altre informazioni, vedere la sezione Osservazioni. |
|
Tentativo di ottenere informazioni di configurazione USB non riuscite. |
Per un elenco di altri valori restituiti che il metodo WdfUsbTargetDeviceCreateWithParameters metodo, vedere Framework Object Creation Errors.
Questo metodo potrebbe anche restituire altri valori NTSTATUS .
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Osservazioni
Windows 8 include un nuovo stack di driver USB per supportare i dispositivi USB 3.0.
Prima che un driver client basato su framework possa usare le nuove funzionalità dello stack di driver USB per Windows 8, il driver deve registrarsi con lo stack di driver USB sottostante caricato da Windows per il dispositivo. Per registrare il driver client, chiamare WdfUsbTargetDeviceCreateWithParameters e specificare una versione del contratto nella struttura WDF_USB_DEVICE_CREATE_CONFIG.
Se il driver client è progettato per compilare, eseguire e usare i miglioramenti e le nuove funzionalità in Windows 8, la versione del contratto client è USBD_CLIENT_CONTRACT_VERSION_602.
In genere, i driver chiamano WdfUsbTargetDeviceCreateWithParameters da un EvtDevicePrepareHardware funzione di callback. I driver possono anche chiamare WdfUsbTargetDeviceCreateWithParameters da un EvtDriverDeviceAdd funzione di callback.
Per informazioni su come i driver client USB WDM interagiscono con lo stack di driver USB 3.0, vedere Best Practices: Using URBs.For information about how WDM USB client drivers interact with the USB 3.0 driver stack, see Best Practices: Using URBs.
Se il driver chiama WdfUsbTargetDeviceCreateWithParameters per creare un oggetto dispositivo USB del framework, il driver deve creare URI solo chiamando WdfUsbTargetDeviceCreateUrb o WdfUsbTargetDeviceCreateIsochUrb.
Se si chiama questo metodo da un driver UMDF, è necessario specificare la direttiva UmdfDispatcher nel file INF del driver. In caso contrario, questo metodo può restituire STATUS_INVALID_PARAMETER. Per altre informazioni su questa direttiva, vedere Specifica delle direttive WDF nei file INF.
Esempi
L'esempio di codice seguente fa parte di un EvtDevicePrepareHardware funzione di callback che chiama WdfUsbTargetDeviceCreateWithParameters. L'esempio archivia l'handle nell'oggetto dispositivo USB framework nello spazio di contesto definito dal driver.
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;
}
...
}
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Universale |
| versione minima di KMDF | 1.11 |
| versione minima di UMDF | 2.0 |
| intestazione | wdfusb.h (include Wdfusb.h) |
| libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| regole di conformità DDI | DriverCreate(kmdf), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf) |