USBD_CreateHandle (usbdlib.h)

  • Artikel

Rutinitas USBD_CreateHandle dipanggil oleh driver klien USB WDM untuk mendapatkan handel USBD. Rutinitas mendaftarkan driver klien dengan tumpukan driver USB yang mendasar.

Catatan untuk Driver Windows Driver Framework (WDF): Jika driver klien Anda adalah driver berbasis WDF, maka Anda tidak memerlukan handel USBD. Driver klien terdaftar dalam panggilannya ke metode WdfUsbTargetDeviceCreateWithParameters .

Sintaks

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

Parameter

[in] DeviceObject

Arahkan ke objek perangkat untuk driver klien.

[in] TargetDeviceObject

Arahkan ke objek perangkat bawah berikutnya di tumpukan perangkat. Driver klien menerima pointer ke objek perangkat tersebut dalam panggilan sebelumnya ke IoAttachDeviceToDeviceStack.

[in] USBDClientContractVersion

Versi kontrak yang didukung driver klien. USBDClientContractVersion harus USBD_CLIENT_CONTRACT_VERSION_602. Untuk informasi selengkapnya, lihat Keterangan.

[in] PoolTag

Tag kumpulan yang digunakan untuk alokasi memori.

[out] USBDHandle

Handel buram yang menunjukkan bahwa driver klien terdaftar dengan tumpukan driver USB. Untuk informasi selengkapnya, lihat Keterangan.

Nilai kembali

Rutinitas mengembalikan kode NTSTATUS. Nilai yang mungkin termasuk tetapi tidak terbatas pada, nilai-nilai ini dalam tabel berikut.

Menampilkan kode Deskripsi
STATUS_SUCCESS
 Panggilan rutin berhasil.
STATUS_INVALID_LEVEL
 Pemanggil tidak berjalan pada nilai IRQL PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER
 Pemanggil melewati salah satu nilai parameter yang tidak valid berikut ini:
  • DeviceObject, TargetDeviceObject, atau USBDHandle adalah NULL.
  • Nilai kontrak klien yang ditentukan dalam USBDClientContractVersion tidak valid.
  • PoolTag adalah nol.

Keterangan

Pendaftaran Versi

Windows 8 menyertakan tumpukan driver USB baru untuk mendukung perangkat USB 3.0. Tumpukan driver USB baru menyediakan beberapa kemampuan baru, seperti dukungan aliran, MDL berantai, dan sebagainya. Sebelum driver klien Anda dapat menggunakan salah satu kemampuan USB tersebut, Anda harus mendaftarkan driver klien dengan tumpukan driver USB dan mendapatkan handel USBD. Handel diperlukan untuk memanggil rutinitas yang menggunakan atau mengonfigurasi kemampuan baru. Untuk mendapatkan handel USBD, panggil USBD_CreateHandle.

Driver klien harus memanggil USBD_CreateHandle terlepas dari apakah perangkat terpasang ke pengontrol host USB 3.0, 2.0, atau 1.1. Jika perangkat terpasang ke pengontrol host USB 3.0, Windows memuat tumpukan driver USB 3.0. Jika tidak, tumpukan driver USB 2.0 dimuat. Dalam kedua kasus, driver klien tidak diharuskan untuk mengetahui versi yang didukung oleh tumpukan driver USB yang mendasar. USBD_CreateHandle menilai versi tumpukan driver dan mengalokasikan sumber daya dengan tepat.

Driver klien harus menentukan USBD_CLIENT_CONTRACT_VERSION_602 dalam parameter USBDClientContractVersion dan mengikuti serangkaian aturan yang dijelaskan dalam Praktik Terbaik: Menggunakan URL.

Memanggil USBD_CreateHandle

Rutinitas USBD_CreateHandle harus dipanggil oleh driver klien Windows Driver Model (WDM) sebelum driver mengirim permintaan lain, melalui URL atau IOCTL, ke tumpukan driver USB. Biasanya, driver klien mendapatkan handel USBD dalam rutinitas AddDevice-nya.

Driver klien Windows Driver Frameworks (WDF) tidak diperlukan untuk memanggil USBD_CreateHandle karena kerangka kerja memanggil rutinitas ini atas nama driver klien selama fase inisialisasi perangkat. Sebagai gantinya, driver klien dapat menentukan versi kontrak kliennya dalam struktur WDF_USB_DEVICE_CREATE_CONFIG dan meneruskannya dalam panggilan ke WdfUsbTargetDeviceCreateWithParameters.

Penyelesaian Panggilan USBD_CreateHandle

Jika panggilan USBD_CreateHandle berhasil, handel USBD yang valid diperoleh dalam parameter USBDHandle . Driver klien harus menggunakan handel USBD dalam permintaan driver klien di masa mendatang ke tumpukan driver USB.

Jika panggilan USBD_CreateHandle gagal, driver klien dapat gagal dalam rutinitas AddDevice.

Setelah driver klien selesai menggunakan handel USBD, driver harus menutup handel dengan memanggil USBD_CloseHandle rutin.

Contoh

Contoh kode berikut menunjukkan cara mendaftarkan driver klien dengan memanggil 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;
    } 

    ...

}

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Membutuhkan WDK untuk Windows 8. Menargetkan Windows Vista dan versi sistem operasi Windows yang lebih baru.
Target Platform Desktop
Header usbdlib.h (termasuk usbdlib.h, usb.h)
Pustaka Usbdex.lib; Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Lihat juga

Mengalokasikan dan Membangun URL

Praktik Terbaik: Menggunakan URL

USBD_CloseHandle