Fungsi WdfUsbTargetPipeReadSynchronously (wdfusb.h)

Artikel
07/16/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetPipeReadSynchronously membangun permintaan baca dan mengirimkannya secara sinkron ke pipa input USB tertentu.

Sintaksis

NTSTATUS WdfUsbTargetPipeReadSynchronously(
  [in]            WDFUSBPIPE                Pipe,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    MemoryDescriptor,
  [out, optional] PULONG                    BytesRead
);

Parameter

[in] Pipe

Handel ke objek pipa kerangka kerja yang diperoleh dengan memanggil WdfUsbInterfaceGetConfiguredPipe.

[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, optional] MemoryDescriptor

Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang dialokasikan pemanggil yang menjelaskan buffer yang akan menerima data dari perangkat. Ukuran buffer harus kelipatan ukuran paket maksimum pipa kecuali driver telah memanggil WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. Untuk informasi selengkapnya tentang buffer ini, lihat bagian Keterangan berikut ini.

[out, optional] BytesRead

Penunjuk ke lokasi yang menerima jumlah byte yang dibaca, jika operasi berhasil. Parameter ini bersifat opsional dan dapat NULL.

Mengembalikan nilai

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

Mengembalikan kode	Deskripsi
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_REQUEST_SEND_OPTIONS yang ditunjukkan oleh RequestOptions salah.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.
STATUS_INVALID_DEVICE_REQUEST	IRQL penelepon tidak PASSIVE_LEVEL, deskriptor memori yang tidak valid ditentukan, jenis pipa tidak valid, arah transfer tidak valid, atau permintaan I/O yang ditentukan sudah diantrekan ke target I/O.
STATUS_INVALID_BUFFER_SIZE	Ukuran buffer bukan kelipatan ukuran paket maksimum pipa.
STATUS_IO_TIMEOUT	Driver menyediakan nilai waktu habis dan permintaan tidak selesai dalam waktu yang dialokasikan.
STATUS_REQUEST_NOT_ACCEPTED	Paket permintaan I/O (IRP ) yang diwakili parameter Permintaan tidak menyediakan struktur IO_STACK_LOCATION yang cukup untuk memungkinkan driver meneruskan permintaan.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Komentar

Gunakan metode WdfUsbTargetPipeReadSynchronously untuk mengirim permintaan baca secara sinkron. Untuk mengirim permintaan baca secara asinkron, gunakan WdfUsbTargetPipeFormatRequestForRead, diikuti oleh WdfRequestSend.

Pipa yang ditentukan parameter Pipa harus berupa pipa input, dan jenis pipa harus WdfUsbPipeTypeBulk atau WdfUsbPipeTypeInterrupt.

Metode WdfUsbTargetPipeReadSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS yang RequestOptions parameter menunjuk ke, 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. Dalam kedua kasus, kerangka kerja memerlukan objek permintaan dan beberapa ruang buffer.

Untuk meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O:

Tentukan handel permintaan yang diterima untuk parameter Permintaan .
Gunakan buffer output permintaan yang diterima untuk parameter WdfUsbTargetPipeReadSynchronously parameter MemoryDescriptor metode.
Driver harus memanggil WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer output permintaan lalu menempatkan handel tersebut dalam struktur WDF_MEMORY_DESCRIPTOR yang MemoryDescriptor menunjuk.

Untuk informasi selengkapnya tentang meneruskan permintaan I/O, lihat Permintaan I/O Penerusan .

Driver sering membagi permintaan I/O yang diterima menjadi permintaan yang lebih kecil yang mereka kirim ke target I/O, sehingga driver Anda mungkin membuat permintaan baru.

Untuk membuat permintaan I/O baru:

Berikan handel permintaan NULL
di WdfUsbTargetPipeReadSynchronously parameter Request metode, 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.
Berikan ruang buffer untuk parameter WdfUsbTargetPipeReadSynchronously metode
MemoryDescriptor.
Driver Anda dapat menentukan ruang buffer ini sebagai buffer yang dialokasikan secara lokal, sebagai handel WDFMEMORY, atau sebagai MDL. Anda dapat menggunakan metode mana pun yang paling nyaman.

Jika perlu, kerangka kerja mengonversi deskripsi buffer menjadi yang benar untuk metode target I/O untuk mengakses buffer data.

Teknik berikut tersedia:
- Menyediakan buffer lokal
  Karena WdfUsbTargetPipeReadSynchronously menangani permintaan I/O secara sinkron, driver dapat membuat buffer permintaan yang lokal untuk rutinitas panggilan, seperti yang ditunjukkan contoh kode berikut.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Menyediakan handel WDFMEMORY
  Panggil WdfMemoryCreate atau WdfMemoryCreatePreallocated untuk mendapatkan handel ke memori yang dikelola kerangka kerja, seperti yang ditunjukkan contoh kode berikut.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
WDFMEMORY  memoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &memoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                  memoryHandle,
                                  NULL);
```
  Atau, driver dapat memanggil WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer output permintaan I/O yang diterima, jika Anda ingin driver meneruskan konten buffer tersebut ke target I/O. Driver tidak boleh menyelesaikan permintaan I/O yang diterima sampai permintaan baru yang WdfUsbTargetPipeReadSynchronously dikirim ke target I/O telah dihapus, digunakan kembali, atau diformat ulang. (WdfUsbTargetPipeReadSynchronously menaikkan jumlah referensi objek memori. Menghapus, menggunakan kembali, atau memformat ulang objek permintaan mengurangi jumlah referensi objek memori.)
- Menyediakan MDL
  Driver dapat memperoleh MDL yang terkait dengan permintaan I/O yang diterima dengan memanggil WdfRequestRetrieveOutputWdmMdl.

Kerangka kerja menetapkan bendera USBD_SHORT_TRANSFER_OK diURB internalnya. Mengatur bendera ini memungkinkan paket terakhir transfer data menjadi kurang dari ukuran paket maksimum.

Driver tidak dapat memanggil WdfUsbTargetPipeReadSynchronously jika telah mengonfigurasi pembaca berkelanjutan untuk pipa.

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

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

Contoh

Contoh kode berikut membuat objek memori kerangka kerja, menginisialisasi struktur WDF_MEMORY_DESCRIPTOR, dan meneruskan struktur ke WdfUsbTargetPipeReadSynchronously. Contoh ini menentukan NULL untuk handel objek permintaan, sehingga kerangka kerja akan membuat objek permintaan baru untuk target I/O.

WDFMEMORY  wdfMemory;
WDF_MEMORY_DESCRIPTOR  readBufDesc;
ULONG  BytesRead;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         readSize,
                         &wdfMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return ;
}

buffer = WdfMemoryGetBuffer(
                            wdfMemory,
                            NULL
                            );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &readBufDesc,
                                  buffer,
                                  readSize
                                  );

status = WdfUsbTargetPipeReadSynchronously(
                                           Pipe,
                                           NULL,
                                           NULL,
                                           &readBufDesc,
                                           &BytesRead
                                           );

Persyaratan

Syarat	Nilai
Platform Target	Universal
versi KMDF Minimum	1.0
versi UMDF Minimum	2.0
Header	wdfusb.h (termasuk Wdfusb.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
aturan kepatuhan DDI	DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf), WriteReqs(kmdf)

Lihat juga

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WdfMemoryBuat

WdfUsbTargetPipeGetInformation

Bagikan melalui