Fungsi WdfUsbTargetPipeFormatRequestForWrite (wdfusb.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfUsbTargetPipeFormatRequestForWrite membangun permintaan tulis untuk pipa output USB, tetapi tidak mengirim permintaan.
Sintaks
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY WriteMemory,
[in, optional] PWDFMEMORY_OFFSET WriteOffset
);
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] WriteMemory
Handel ke objek memori kerangka kerja. Objek ini mewakili buffer yang berisi data yang akan dikirim ke pipa. Untuk informasi selengkapnya tentang buffer ini, lihat bagian Keterangan berikut ini.
[in, optional] WriteOffset
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 tulis, untuk transfer data. Jika pointer ini NULL, transfer data dimulai di awal buffer, dan ukuran transfer adalah ukuran buffer.
Mengembalikan nilai
WdfUsbTargetPipeFormatRequestForWrite mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:
| Menampilkan kode | Deskripsi |
|---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Memori tidak cukup tersedia. |
|
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. |
|
Offset yang ditentukan parameter Offset tidak valid. |
|
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 WdfUsbTargetPipeFormatRequestForWrite, diikuti oleh WdfRequestSend, untuk mengirim permintaan tulis baik secara sinkron maupun asinkron. Atau, gunakan metode WdfUsbTargetPipeWriteSynchronously untuk mengirim permintaan tulis secara sinkron.
Pipa yang ditentukan harus berupa pipa output, 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 WdfUsbTargetPipeFormatRequestForWrite.
-
Gunakan buffer input permintaan yang diterima untuk parameter WriteMemory metode WdfUsbTargetPipeFormatRequestForWrite.
Driver harus memanggil WdfRequestRetrieveInputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input permintaan dan menggunakan handel tersebut sebagai nilai untuk WriteMemory.
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 WdfUsbTargetPipeFormatRequestForWrite.
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 WriteMemory metode WdfUsbTargetPipeFormatRequestForWrite.
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 WdfRequestRetrieveInputMemory 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.
Beberapa panggilan ke WdfUsbTargetPipeFormatRequestForWrite 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 WdfUsbTargetPipeFormatRequestForWrite), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetPipeFormatRequestForWrite 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 tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.
Untuk informasi selengkapnya tentang metode WdfUsbTargetPipeFormatRequestForWrite 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 EvtIoWrite yang meneruskan permintaan tulis ke pipa USB. Contoh memanggil WdfRequestRetrieveInputMemory untuk mendapatkan buffer input permintaan, lalu memformat permintaan tulis sehingga permintaan dapat dikirim ke pipa USB. Selanjutnya, contoh mendaftarkan fungsi panggilan balik CompletionRoutine . Akhirnya, ia mengirim permintaan ke pipa USB.
VOID
OsrFxEvtIoWrite(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
NTSTATUS status;
WDFUSBPIPE pipe;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkWritePipe;
status = WdfRequestRetrieveInputMemory(
Request,
&reqMemory
);
if (!NT_SUCCESS(status)){
goto Exit;
}
status = WdfUsbTargetPipeFormatRequestForWrite(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestWriteCompletionRoutine,
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
| 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) |