Fungsi WdfUsbTargetDeviceFormatRequestForUrb (wdfusb.h)
[Berlaku untuk KMDF saja]
Metode WdfUsbTargetDeviceFormatRequestForUrb membangun permintaan USB untuk perangkat USB tertentu, menggunakan parameter permintaan yang dijelaskan oleh URB, tetapi tidak mengirim permintaan.
Sintaks
NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] WDFMEMORY UrbMemory,
[in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);
Parameter
[in] UsbDevice
Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.
[in] Request
Handel ke objek permintaan kerangka kerja. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in] UrbMemory
Handel ke objek memori kerangka kerja yang berisi struktur URB atau salah satu anggota serikat struktur. (Semua anggota serikat struktur URB berisi struktur _URB_HEADER .)
Jika driver sebelumnya disebut WdfUsbTargetDeviceCreateWithParameters untuk membuat UsbDevice, driver harus menggunakan WdfUsbTargetDeviceCreateUrb atau WdfUsbTargetDeviceCreateIsochUrb untuk membuat URB yang terkandung dalam objek memori ini. Jika tidak, pemeriksaan bug terjadi.
[in, optional] UrbMemoryOffset
Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok offset byte opsional dan nilai panjang. Kerangka kerja menggunakan nilai-nilai ini untuk menentukan alamat awal URB dalam memori yang ditentukan UrbMemory . Jika pointer ini NULL, URB terletak di awal memori UrbMemory .
Nilai kembali
WdfUsbTargetDeviceFormatRequestForUrb mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Memori tidak cukup. |
|
Offset yang ditentukan parameter UsbMemoryOffset tidak valid. |
Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.
Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.
Keterangan
Gunakan WdfUsbTargetDeviceFormatRequestForUrb, diikuti oleh WdfRequestSend, untuk mengirim permintaan transfer kontrol USB baik secara sinkron atau asinkron. Atau, gunakan metode WdfUsbTargetDeviceSendUrbSynchronously untuk mengirim permintaan secara sinkron.
Anda dapat meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, atau Anda dapat membuat dan mengirim permintaan baru.
Untuk meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfUsbTargetDeviceFormatRequestForUrb.
Untuk membuat permintaan I/O baru, panggil WdfRequestCreate untuk melakukan pra-alokasi objek permintaan. Berikan handel permintaan untuk parameter Permintaan metode WdfUsbTargetDeviceFormatRequestForUrb. Anda dapat menggunakan kembali objek permintaan dengan memanggil WdfRequestReuse. Fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat melakukan pra-alokasi objek permintaan untuk perangkat.
Setelah memanggil WdfUsbTargetDeviceFormatRequestForUrb untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O. Jangan gunakan opsi kirim dan lupakan untuk mengirim permintaan.
Beberapa panggilan ke WdfUsbTargetDeviceFormatRequestForUrb yang menggunakan permintaan yang sama tidak menyebabkan alokasi sumber daya tambahan. Oleh karena itu, untuk mengurangi kemungkinan WdfRequestCreate akan mengembalikan STATUS_INSUFFICIENT_RESOURCES, fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat memanggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan untuk perangkat. Driver kemudian dapat menggunakan kembali (panggil WdfRequestReuse), format ulang (panggil WdfUsbTargetDeviceFormatRequestForUrb), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetDeviceFormatRequestForUrb untuk objek permintaan yang digunakan kembali akan mengembalikan STATUS_SUCCESS, jika nilai parameter tidak berubah. (Jika driver tidak memanggil metode pemformatan permintaan yang sama setiap kali, sumber daya tambahan mungkin dialokasikan.)
Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.
Untuk informasi selengkapnya tentang metode WdfUsbTargetDeviceFormatRequestForUrb dan target I/O USB, lihat Target I/O USB.
Contoh
Contoh kode berikut membuat objek memori untuk menyimpan struktur URB, menginisialisasi struktur URB, dan memanggil WdfUsbTargetDeviceFormatRequestForUrb untuk memformat permintaan yang menggunakan konten struktur URB. Kemudian, contoh mendaftarkan fungsi panggilan balik CompletionRoutine dan mengirim permintaan ke target I/O.
WDFMEMORY urbMemory;
URB *urbBuffer;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
&urbMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
urbMemory,
NULL
);
urbBuffer->UrbHeader.Function = URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;
status = WdfUsbTargetDeviceFormatRequestForUrb(
deviceContext->WdfUsbTargetDevice,
request,
urbMemory,
NULL
);
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Header | wdfusb.h (termasuk Wdfusb.h) |
Pustaka | Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.) |
IRQL | <=DISPATCH_LEVEL |
Aturan kepatuhan DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk