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 gli 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 potrebbero essere restituiti dal metodo WdfUsbTargetDeviceCreate, 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
Un driver che usa una destinazione I/O USB deve chiamare WdfUsbTargetDeviceCreare dopo che il dispositivo entra in funzione (D0). In genere, un driver chiama WdfUsbTargetDeviceCreate dall'interno del proprio EvtDevicePrepareHardware funzione di callback. Il driver non può chiamare WdfUsbTargetDeviceCreate dall'interno del proprio EvtDriverDeviceAdd funzione di callback.
WdfUsbTargetDeviceCreare 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 per oggetti dispositivo USB framework.
L'elemento padre di ogni oggetto dispositivo USB è l'oggetto driver del driver 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, vedere Destinazioni I/O USB.
Esempi
L'esempio di codice seguente fa parte di un EvtDevicePrepareHardware funzione di callback che chiama WdfUsbTargetDeviceCreate. L'esempio archivia l'handle dell'oggetto dispositivo USB nello spazio del 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;
}
...
}
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Universale |
| versione minima di KMDF | 1.0 |
| 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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |