funzione USBD_CreateHandle (usbdlib.h)

Articolo
08/07/2023

La routine USBD_CreateHandle viene chiamata da un driver client USB WDM per ottenere un handle USBD. La routine registra il driver client con lo stack di driver USB sottostante.

Nota per driver Windows Driver Framework (WDF): Se il driver client è un driver basato su WDF, non è necessario l'handle USBD. Il driver client viene registrato nella chiamata al metodo WdfUsbTargetDeviceCreateWithParameters .

Sintassi

NTSTATUS USBD_CreateHandle(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  PDEVICE_OBJECT TargetDeviceObject,
  [in]  ULONG          USBDClientContractVersion,
  [in]  ULONG          PoolTag,
  [out] USBD_HANDLE    *USBDHandle
);

Parametri

[in] DeviceObject

Puntatore all'oggetto dispositivo per il driver client.

[in] TargetDeviceObject

Puntatore all'oggetto dispositivo inferiore successivo nello stack di dispositivi. Il driver client riceve un puntatore all'oggetto dispositivo in una chiamata precedente a IoAttachDeviceToDeviceStack.

[in] USBDClientContractVersion

Versione del contratto supportata dal driver client. USBDClientContractVersion deve essere USBD_CLIENT_CONTRACT_VERSION_602. Per altre informazioni, vedere la sezione Osservazioni.

[in] PoolTag

Tag del pool usato per le allocazioni di memoria.

[out] USBDHandle

Handle opaco che indica che il driver client è stato registrato con lo stack di driver USB. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

La routine restituisce un codice NTSTATUS. I valori possibili includono, ad esempio, questi valori nella tabella seguente.

Codice restituito	Descrizione
STATUS_SUCCESS	Chiamata di routine riuscita.
STATUS_INVALID_LEVEL	Il chiamante non è in esecuzione in corrispondenza del valore IRQL PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Il chiamante ha passato uno dei valori di parametro non validi seguenti: DeviceObject, TargetDeviceObject o USBDHandle è NULL. Il valore del contratto client specificato in USBDClientContractVersion non è valido. PoolTag è zero.

Commenti

Registrazione della versione

Windows 8 include un nuovo stack di driver USB per supportare dispositivi USB 3.0. Il nuovo stack di driver USB offre diverse nuove funzionalità, ad esempio il supporto del flusso, gli ELENCHI MDL concatenati e così via. Prima che il driver client possa usare una qualsiasi di queste funzionalità USB, è necessario registrare il driver client con lo stack di driver USB e ottenere un handle USBD. L'handle è necessario per chiamare routine che usano o configurano le nuove funzionalità. Per ottenere un handle USBD, chiamare USBD_CreateHandle.

Il driver client deve chiamare USBD_CreateHandle indipendentemente dal fatto che il dispositivo sia collegato a un controller host USB 3.0, 2.0 o 1.1. Se il dispositivo è collegato a un controller host USB 3.0, Windows carica lo stack di driver USB 3.0. In caso contrario, lo stack di driver USB 2.0 viene caricato. In entrambi i casi, il driver client non è necessario conoscere la versione supportata dallo stack di driver USB sottostante. USBD_CreateHandle valuta la versione dello stack di driver e alloca le risorse in modo appropriato.

Il driver client deve specificare USBD_CLIENT_CONTRACT_VERSION_602 nel parametro USBDClientContractVersion e seguire il set di regole descritte in Procedure consigliate : Uso degli URL.

Chiamata di USBD_CreateHandle

La routine USBD_CreateHandle deve essere chiamata da un driver client Windows Driver Model (WDM) prima che il driver invii qualsiasi altra richiesta, tramite URL o IOCTL, allo stack di driver USB. In genere, il driver client ottiene l'handle USBD nella routine AddDevice.

Un driver client WDF (Windows Driver Frameworks) non è necessario chiamare USBD_CreateHandle perché il framework chiama questa routine per conto del driver client durante la fase di inizializzazione del dispositivo. Il driver client può invece specificare la versione del contratto client nella struttura WDF_USB_DEVICE_CREATE_CONFIG e passarla alla chiamata a WdfUsbTargetDeviceCreateWithParameters.

completamento chiamata USBD_CreateHandle

Se la chiamata USBD_CreateHandle ha esito positivo, viene ottenuto un handle USBD valido nel parametro USBDHandle . Il driver client deve usare l'handle USBD nelle richieste future del driver client allo stack di driver USB.

Se la chiamata USBD_CreateHandle ha esito negativo, il driver client può non riuscire la routine AddDevice.

Al termine dell'uso dell'handle USBD, il driver deve chiudere l'handle chiamando la routine USBD_CloseHandle .

Esempio

Il codice di esempio seguente illustra come registrare un driver client chiamando USBD_CreateHandle.

DRIVER_ADD_DEVICE MyAddDevice;

NTSTATUS MyAddDevice( __in PDRIVER_OBJECT  DriverObject,
                     __in PDEVICE_OBJECT  PhysicalDeviceObject)
{

    NTSTATUS            ntStatus;
    PDEVICE_OBJECT      deviceObject;
    PDEVICE_EXTENSION   deviceExtension;
    PDEVICE_OBJECT      stackDeviceObject;
    USBD_HANDLE         usbdHandle;

    ...

        ntStatus = IoCreateDevice(DriverObject,
        sizeof(DEVICE_EXTENSION),
        NULL,
        FILE_DEVICE_UNKNOWN,
        FILE_AUTOGENERATED_DEVICE_NAME,
        FALSE,
        &deviceObject);


    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        //     Attach the FDO to the top of the PDO in the client driver's 
        //  device stack.

        deviceExtension->StackDeviceObject = IoAttachDeviceToDeviceStack (
        deviceObject,
        PhysicalDeviceObject);

    ...

        // Initialize the DeviceExtension

        deviceExtension = deviceObject->DeviceExtension;

    ...

        //Register the client driver with the USB driver stack.
        //Obtain a USBD handle for registration.

        ntStatus = USBD_CreateHandle(deviceObject, 
        deviceExtension->StackDeviceObject,
        USBD_CLIENT_CONTRACT_VERSION_602,
        POOL_TAG,
        &deviceExtension->USBDHandle);

    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        // Call USBD_QueryUsbCapability to determine 
        // stream support. 

        ntStatus = USBD_QueryUsbCapability ( deviceExtension->USBDHandle,  
        (GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,  
        sizeof(ULONG),  
        (PUCHAR) &deviceExtension.MaxSupportedStreams);  


    if (!NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->MaxSupportedStreams = 0;
        ntStatus = STATUS_SUCCESS;
    } 

    ...

}

Requisiti

Requisito	Valore
Client minimo supportato	Richiede WDK per Windows 8. È destinato a Windows Vista e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Desktop
Intestazione	usbdlib.h (include usbdlib.h, usb.h)
Libreria	Usbdex.lib; Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

Vedi anche

Allocazione e compilazione di URI

Procedure consigliate: Uso degli URI

USBD_CloseHandle

Condividi tramite