USBD_CreateHandle (usbdlib.h)
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 |
---|---|
|
Panggilan rutin berhasil. |
|
Pemanggil tidak berjalan pada nilai IRQL PASSIVE_LEVEL. |
|
Pemanggil melewati salah satu nilai parameter yang tidak valid berikut ini:
|
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