Fungsi WdfUsbTargetDeviceSendUrbSynchronously (wdfusb.h)

Artikel
07/16/2024

[Hanya berlaku untuk KMDF]

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

Sintaksis

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 NULL. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini.

[in, optional] RequestOptions

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

[in] Urb

Penunjuk ke struktur URB yang diinisialisasi pemanggil.

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

Mengembalikan nilai

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

Mengembalikan 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 menyediakan 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.

Komentar

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 batas waktu dalam RequestOptions struktur WDF_REQUEST_SEND_OPTIONS parameter, 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 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 driver Anda EvtDriverDeviceAdd 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 RequestOptionsNULL non-, apakah driver menyediakan parameter NULL non-atau parameter PermintaanNULL . 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 metode dan target USB I/O, lihat Target I/O USB.

Contoh

Contoh kode berikut menginisialisasi struktur URB dan panggilan 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

Syarat	Nilai
Platform Target	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)