Fungsi WdfUsbTargetDeviceFormatRequestForCyclePort (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfUsbTargetDeviceFormatRequestForCyclePort membangun permintaan siklus daya untuk port tempat perangkat tertentu terpasang, tetapi tidak mengirim permintaan.

Sintaks

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

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.

Nilai kembali

WdfUsbTargetDeviceFormatRequestForCyclePort mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_STATE	Perangkat USB perangkat tidak tersedia.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Gunakan WdfUsbTargetDeviceFormatRequestForCyclePort, diikuti oleh WdfRequestSend, untuk mengirim permintaan siklus daya baik secara sinkron atau asinkron. Atau, gunakan metode WdfUsbTargetDeviceCyclePortSynchronously untuk mengirim permintaan secara sinkron.

Sebelum driver memanggil WdfRequestSend, driver harus memanggil WdfIoTargetStop dan harus menyelesaikan atau membatalkan semua permintaan I/O yang telah dikirim ke target I/O. Driver tidak boleh mengirim permintaan I/O tambahan ke target I/O hingga permintaan siklus selesai.

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 WdfUsbTargetDeviceFormatRequestForCyclePort.

Untuk membuat permintaan I/O baru, panggil WdfRequestCreate untuk melakukan pra-alokasi objek permintaan. Berikan handel permintaan untuk parameter Permintaan metode WdfUsbTargetDeviceFormatRequestForCyclePort. 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 WdfUsbTargetDeviceFormatRequestForCyclePort untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O. Panggilan ke WdfRequestSend ini harus dilakukan di IRQL = PASSIVE_LEVEL.

Beberapa panggilan ke WdfUsbTargetDeviceFormatRequestForCyclePort 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), reformat (panggil WdfUsbTargetDeviceFormatRequestForCyclePort), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetDeviceFormatRequestForCyclePort 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 selengkapnya tentang metode WdfUsbTargetDeviceFormatRequestForCyclePort dan target I/O USB, lihat Target I/O USB.

Contoh

Contoh kode berikut memformat permintaan siklus daya, mendaftarkan fungsi panggilan balik CompletionRoutine , dan mengirim permintaan ke target I/O.

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
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)