Fungsi WdfUsbTargetDeviceSendUrbSynchronously (wdfusb.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfUsbTargetDeviceSendUrbSynchronously mengirimkan permintaan USB secara sinkron ke perangkat USB tertentu, menggunakan parameter permintaan yang dijelaskan oleh URB.

Sintaks

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

Parameter

[in] UsbDevice

Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

Handel ke objek permintaan kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] RequestOptions

Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang dialokasikan penelepon yang menentukan opsi untuk permintaan tersebut. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] Urb

Penunjuk ke struktur URB yang diinisialisasi penelepon.

Jika driver sebelumnya disebut WdfUsbTargetDeviceCreateWithParameters untuk membuat UsbDevice, driver harus menggunakan WdfUsbTargetDeviceCreateUrb atau WdfUsbTargetDeviceCreateIsochUrb untuk membuat URB ini.

Nilai kembali

WdfUsbTargetDeviceSendUrbSynchronously mengembalikan nilai status penyelesaian target I/O jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INVALID_DEVICE_REQUEST	IRQL penelepon tidak valid.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.
STATUS_IO_TIMEOUT	Driver memberikan nilai waktu habis dan permintaan tidak selesai dalam waktu yang dialokasikan.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Gunakan metode WdfUsbTargetDeviceSendUrbSynchronously untuk mengirim permintaan transfer kontrol USB secara sinkron. Untuk mengirim permintaan tersebut secara asinkron, gunakan WdfUsbTargetDeviceFormatRequestForUrb, diikuti oleh WdfRequestSend.

Metode WdfUsbTargetDeviceSendUrbSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS parameter RequestOptions, atau kecuali kesalahan terdeteksi.

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

Untuk membuat dan mengirim permintaan baru, berikan handel permintaan NULL untuk parameter Permintaan , atau buat objek permintaan baru dan berikan handelnya:

Jika Anda menyediakan handel permintaan NULL , kerangka kerja menggunakan objek permintaan internal. Teknik ini mudah digunakan, tetapi driver tidak dapat membatalkan permintaan.
Jika Anda memanggil WdfRequestCreate untuk membuat satu atau beberapa objek permintaan, Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Teknik ini memungkinkan fungsi panggilan balik EvtDriverDeviceAdd driver Anda untuk melakukan pra-alokasi objek permintaan untuk perangkat. Selain itu, utas driver lain dapat memanggil WdfRequestCancelSentRequest untuk membatalkan permintaan, jika perlu.

Driver Anda dapat menentukan parameter RequestOptionsnon-NULL, baik driver menyediakan parameter permintaannon-NULL atau NULL. Misalnya, Anda dapat menggunakan parameter RequestOptions untuk menentukan nilai waktu habis.

Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.

Untuk informasi selengkapnya tentang metode WdfUsbTargetDeviceSendUrbSynchronously dan target USB I/O, lihat Target I/O USB.

Contoh

Contoh kode berikut menginisialisasi struktur URB dan memanggil WdfUsbTargetDeviceSendUrbSynchronously.

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

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	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)