Funzione WdfUsbTargetDeviceCreate (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetDeviceCreate crea un oggetto dispositivo USB framework per un oggetto dispositivo framework specificato e apre il dispositivo USB per le operazioni di I/O.
Sintassi
NTSTATUS WdfUsbTargetDeviceCreate(
[in] WDFDEVICE Device,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFUSBDEVICE *UsbDevice
);
Parametri
[in] Device
Handle per un oggetto dispositivo framework.
[in, optional] Attributes
Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES fornita dal chiamante che contiene attributi per il nuovo oggetto dispositivo USB. 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
WdfUsbTargetDeviceCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente per creare un nuovo oggetto dispositivo USB. |
|
Tentativo di ottenere informazioni di configurazione USB non riuscite. |
Per un elenco di altri valori restituiti che il metodo WdfUsbTargetDeviceCreate potrebbe restituire, vedere Errori di creazione di oggetti framework.
Questo metodo potrebbe anche restituire altri valori NTSTATUS.
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Commenti
Un driver che usa una destinazione di I/O USB deve chiamare WdfUsbTargetDeviceCreate dopo che il dispositivo entra nel proprio stato di lavoro (D0). In genere, un driver chiama WdfUsbTargetDeviceCreate dall'interno della relativa funzione di callback EvtDevicePrepareHardware . Il driver non può chiamare WdfUsbTargetDeviceCreate dall'interno della relativa funzione di callback EvtDriverDeviceAdd .
WdfUsbTargetDeviceCreate ottiene il descrittore del dispositivo USB e il primo descrittore di configurazione USB dal dispositivo e li archivia. Crea anche un oggetto interfaccia USB del framework per ogni interfaccia nella prima configurazione del dispositivo. Per determinare il numero di interfacce supportate dalla configurazione, il driver può chiamare WdfUsbTargetDeviceGetNumInterfaces.
Dopo aver chiamato WdfUsbTargetDeviceCreate, il driver può chiamare metodi aggiuntivi dell'oggetto dispositivo USB del framework.
L'elemento padre di ogni oggetto dispositivo USB è l'oggetto driver del framework del driver. Il driver non può modificare questo elemento padre e il membro ParentObject o la struttura WDF_OBJECT_ATTRIBUTES deve essere NULL.
Per altre informazioni sul metodo WdfUsbTargetDeviceCreate e sulle destinazioni di I/O USB, vedi Destinazioni di I/O USB.
Esempio
L'esempio di codice seguente fa parte di una funzione di callback EvtDevicePrepareHardware che chiama WdfUsbTargetDeviceCreate. L'esempio archivia l'handle dell'oggetto dispositivo USB nello spazio di contesto definito dal driver.
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;
}
...
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1,0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfusb.h (include Wdfusb.h) |
| Libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| Regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |