Fungsi WdfUsbTargetPipeFormatRequestForRead (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetPipeFormatRequestForRead membangun permintaan baca untuk pipa input USB, tetapi tidak mengirim permintaan.

Sintaks

NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         ReadMemory,
  [in, optional] PWDFMEMORY_OFFSET ReadOffset
);

Parameter

[in] Pipe

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

[in] Request

Handel ke objek permintaan kerangka kerja. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] ReadMemory

Handel ke objek memori kerangka kerja. Objek ini mewakili buffer yang akan menerima data dari pipa. Ukuran buffer harus kelipatan ukuran paket maksimum pipa kecuali driver telah memanggil WdfUsbTargetPipeSetNoMaximumPacketSizeCheck. Untuk informasi selengkapnya tentang buffer ini, lihat bagian Keterangan berikut ini.

[in, optional] ReadOffset

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 dan panjang awal, dalam buffer baca, untuk transfer data. Jika pointer ini NULL, transfer data dimulai di awal buffer, dan ukuran transfer adalah ukuran buffer.

Nilai kembali

WdfUsbTargetPipeFormatRequestForRead mengembalikan STATUS_SUCCESS 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_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.
STATUS_INVALID_DEVICE_REQUEST	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_INTEGER_OVERFLOW	Offset yang ditentukan parameter Offset tidak valid.
STATUS_INVALID_BUFFER_SIZE	Ukuran buffer bukan kelipatan ukuran paket maksimum pipa. Ukuran buffer harus kelipatan ukuran paket maksimum pipa kecuali driver telah memanggil WdfUsbTargetPipeSetNoMaximumPacketSizeCheck.
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 mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

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

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

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 metode WdfUsbTargetPipeFormatRequestForRead.
Gunakan buffer output permintaan yang diterima untuk parameter ReadMemory metode WdfUsbTargetPipeFormatRequestForRead.
Driver harus memanggil WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer output permintaan, dan menggunakan handel tersebut sebagai nilai untuk parameter ReadMemory .

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

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:

Buat objek permintaan baru dan berikan handelnya untuk parameter Permintaan metode WdfUsbTargetPipeFormatRequestForRead.
Panggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan. Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat melakukan pra-alokasi objek permintaan untuk perangkat.
Berikan ruang buffer, dan berikan handel buffer untuk parameter ReadMemory metode WdfUsbTargetPipeFormatRequestForRead.
Driver Anda harus menentukan ruang buffer ini sebagai handel WDFMEMORY ke memori yang dikelola kerangka kerja. Driver Anda dapat melakukan salah satu hal berikut:
- Panggil WdfMemoryCreate atau WdfMemoryCreatePreallocated untuk membuat buffer memori baru, jika Anda ingin driver meneruskan buffer baru ke target I/O.
- Panggil WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori yang mewakili buffer permintaan I/O yang diterima, jika Anda ingin driver meneruskan konten buffer tersebut ke target I/O.
Perhatikan bahwa jika driver Anda memanggil WdfRequestRetrieveOutputMemory dan meneruskan handel memori ke WdfUsbTargetPipeFormatRequestForRead, driver tidak boleh menyelesaikan permintaan I/O yang diterima sampai setelah driver menghapus, menggunakan kembali, atau memformat ulang objek permintaan baru yang dibuat driver. (WdfUsbTargetPipeFormatRequestForRead menaikkan jumlah referensi objek memori. Menghapus, menggunakan kembali, atau memformat ulang objek permintaan mengurangi jumlah referensi objek memori.)

Setelah memanggil WdfUsbTargetPipeFormatRequestForRead untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O.

Beberapa panggilan ke WdfUsbTargetPipeFormatRequestForRead 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 WdfUsbTargetPipeFormatRequestForRead), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetPipeFormatRequestForRead 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.)

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

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

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

Contoh

Contoh kode berikut berasal dari driver sampel kmdf_fx2 . Contoh ini adalah fungsi panggilan balik EvtIoRead yang meneruskan permintaan baca ke pipa USB. Contoh memanggil WdfRequestRetrieveOutputMemory untuk mendapatkan buffer output permintaan, lalu memformat permintaan baca sehingga permintaan dapat dikirim ke pipa USB. Selanjutnya, contoh mendaftarkan fungsi panggilan balik CompletionRoutine . Akhirnya, ia mengirim permintaan ke pipa USB.

VOID 
OsrFxEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // First, validate input parameters.
    //
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkReadPipe;
 
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
 
    status = WdfUsbTargetPipeFormatRequestForRead(
                                                  pipe,
                                                  Request,
                                                  reqMemory,
                                                  NULL
                                                  ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   pipe
                                   );
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }

 
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Persyaratan

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