Fungsi WdfIoTargetFormatRequestForWrite (wdfiotarget.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfIoTargetFormatRequestForWrite membangun permintaan tulis untuk target I/O tetapi tidak mengirim permintaan.
Sintaks
NTSTATUS WdfIoTargetFormatRequestForWrite(
[in] WDFIOTARGET IoTarget,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY InputBuffer,
[in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
[in, optional] PLONGLONG DeviceOffset
);
Parameter
[in] IoTarget
Handel ke objek target I/O lokal atau jarak jauh yang diperoleh dari panggilan sebelumnya ke WdfDeviceGetIoTarget atau WdfIoTargetCreate, atau dari metode yang disediakan target I/O khusus.
[in] Request
Handel ke objek permintaan kerangka kerja. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in, optional] InputBuffer
Handel ke objek memori kerangka kerja. Objek ini mewakili buffer yang berisi data yang akan dikirim ke target I/O. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.
[in, optional] InputBufferOffset
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 input, untuk transfer data. Jika pointer ini NULL, transfer data dimulai di awal buffer input, dan ukuran transfer adalah ukuran buffer.
[in, optional] DeviceOffset
Pointer ke lokasi yang menentukan offset awal untuk transfer. Target I/O (yaitu, driver berikutnya yang lebih rendah) menentukan cara menggunakan nilai ini. Misalnya, driver dalam tumpukan driver disk mungkin menentukan offset dari awal disk. Target I/O mendapatkan informasi ini di anggota Parameters.Write.DeviceOffset dari struktur WDF_REQUEST_PARAMETERS permintaan. Penunjuk ini bersifat opsional. Sebagian besar driver mengatur penunjuk ini ke NULL.
Nilai kembali
WdfIoTargetFormatRequestForWrite mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Panjang transfer lebih besar dari panjang buffer, atau permintaan I/O sudah diantrekan ke target I/O. |
|
Kerangka kerja tidak dapat mengalokasikan sumber daya sistem (biasanya memori). |
|
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 metode WdfIoTargetFormatRequestForWrite , diikuti oleh metode WdfRequestSend , untuk mengirim permintaan tulis baik secara sinkron atau asinkron. Atau, gunakan metode WdfIoTargetSendWriteSynchronously untuk mengirim permintaan tulis secara sinkron.
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 WdfIoTargetFormatRequestForWrite.
-
Gunakan buffer input permintaan yang diterima untuk parameter InputBuffer metode WdfIoTargetFormatRequestForWrite.
Driver harus memanggil WdfRequestRetrieveInputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input permintaan dan harus menggunakan handel tersebut sebagai nilai untuk InputBuffer.
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 WdfIoTargetFormatRequestForWrite.
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.
-
Sediakan ruang buffer, dan berikan handel buffer untuk parameter InputBuffer metode WdfIoTargetFormatRequestForWrite.
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.
Setelah driver memanggil WdfIoTargetFormatRequestForWrite untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O.
Beberapa panggilan ke WdfIoTargetFormatRequestForWrite 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), reformat (panggil WdfIoTargetFormatRequestForWrite), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfIoTargetFormatRequestForWrite 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 WdfIoTargetFormatRequestForWrite, lihat Mengirim Permintaan I/O ke Target I/O Umum.
Untuk informasi selengkapnya tentang target I/O, lihat Menggunakan Target I/O.
Contoh
Contoh kode berikut membuat objek memori kerangka kerja untuk buffer input permintaan tulis, memformat permintaan tulis, mendaftarkan fungsi panggilan balik CompletionRoutine , dan mengirim permintaan tulis ke target I/O.
WDFREQUEST request;
NTSTATUS status;
WDFMEMORY memory;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
DRIVER_TAG,
WRITE_BUF_SIZE,
&memory,
NULL
);
if (!NT_SUCCESS(status)) {
return status;
}
status = WdfIoTargetFormatRequestForWrite(
IoTarget,
request,
memory,
NULL,
NULL
);
if (!NT_SUCCESS(status)) {
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyReadRequestCompletionRoutine,
targetInfo
);
if (WdfRequestSend(
request,
IoTarget,
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Versi UMDF minimum | 2.0 |
Header | wdfiotarget.h (termasuk Wdf.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) |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk