Funzione WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)

Articolo
08/08/2023

[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 del 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 del framework.

[in, optional] Attributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES fornita dal chiamante che contiene 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
STATUS_INFO_LENGTH_MISMATCH	Il parametro Config non è la dimensione corretta.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente per creare un nuovo oggetto dispositivo USB del framework.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido. Per altre informazioni, vedere la sezione Osservazioni.
STATUS_UNSUCCESSFUL	Tentativo di ottenere informazioni di configurazione USB non riuscite.

Per un elenco di altri valori restituiti che il metodo WdfUsbTargetDeviceCreateWithParameters 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

Windows 8 include un nuovo stack di driver USB per supportare 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 deve 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 dall'interno di una funzione di callback EvtDevicePrepareHardware . I driver possono anche chiamare WdfUsbTargetDeviceCreateWithParameters dall'interno di una funzione di callback EvtDriverDeviceAdd .

Per informazioni su come i driver client USB WDM interagiscono con lo stack di driver USB 3.0, vedere Procedure consigliate: Uso degli URB.

Se il driver chiama WdfUsbTargetDeviceCreateWithParameters per creare un oggetto dispositivo USB framework, il driver deve creare URL 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.

Esempio

L'esempio di codice seguente fa parte di una funzione di callback EvtDevicePrepareHardware che chiama WdfUsbTargetDeviceCreateWithParameters. Nell'esempio l'handle viene archiviato nell'oggetto dispositivo USB del 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;
    }
...
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.11
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), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)