Fungsi WdfIoTargetSendWriteSynchronously (wdfiotarget.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfIoTargetSendWriteSynchronously membangun permintaan tulis dan mengirimkannya secara sinkron ke target I/O.
Sintaks
NTSTATUS WdfIoTargetSendWriteSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_MEMORY_DESCRIPTOR InputBuffer,
[in, optional] PLONGLONG DeviceOffset,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesWritten
);
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, optional] Request
Handel ke objek permintaan kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.
[in, optional] InputBuffer
Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang dialokasikan penelepon yang menjelaskan buffer yang berisi data yang akan ditulis ke perangkat. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.
[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.
[in, optional] RequestOptions
Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang dialokasikan pemanggil yang menentukan opsi untuk permintaan. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.
[out, optional] BytesWritten
Penunjuk ke lokasi yang menerima jumlah byte yang ditulis, jika operasi berhasil. Penunjuk ini bersifat opsional dan dapat berupa NULL.
Nilai kembali
Jika operasi berhasil, WdfIoTargetSendWriteSynchronously kembali setelah permintaan I/O selesai, dan nilai yang dikembalikan adalah nilai status penyelesaian permintaan. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Ukuran struktur WDF_REQUEST_SEND_OPTIONS yang ditujukan parameter RequestOptions salah. |
|
Permintaan I/O sudah diantrekan ke target I/O. |
|
Kerangka kerja tidak dapat mengalokasikan sumber daya sistem (biasanya memori). |
|
Driver memberikan nilai waktu habis dan permintaan tidak selesai dalam waktu yang dialokasikan. |
|
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 WdfIoTargetSendWriteSynchronously untuk mengirim permintaan tulis secara sinkron. Untuk mengirim permintaan tulis secara asinkron, gunakan metode WdfIoTargetFormatRequestForWrite , diikuti dengan metode WdfRequestSend .
WdfIoTargetSendWriteSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai batas waktu dalam struktur WDF_REQUEST_SEND_OPTIONS parameter RequestOptions, 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 metode WdfIoTargetSendWriteSynchronously.
-
Gunakan buffer input permintaan yang diterima untuk parameter InputBuffer metode WdfIoTargetSendWriteSynchronously.
Driver harus memanggil WdfRequestRetrieveInputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input permintaan dan kemudian menempatkan handel tersebut dalam struktur WDF_MEMORY_DESCRIPTOR yang disediakan driver untuk parameter 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:
-
Berikan handel permintaan NULL untuk parameter Permintaan metode WdfIoTargetSendWriteSynchronously, 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 EvtDriverDeviceAdd driver Anda 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 RequestOptionsnon-NULL, baik driver menyediakan parameter permintaannon-NULL atau NULL. Anda dapat, misalnya, menggunakan parameter RequestOptions untuk menentukan nilai waktu habis.
-
Berikan ruang buffer untuk parameter InputBuffer metode WdfIoTargetSendWriteSynchronously.
Driver Anda dapat menentukan ruang buffer ini sebagai buffer yang dialokasikan secara lokal, sebagai handel WDFMEMORY, atau sebagai daftar deskriptor memori (MDL). Anda dapat menggunakan metode mana pun yang paling nyaman.
Jika perlu, kerangka kerja mengonversi deskripsi buffer menjadi deskripsi yang benar untuk metode target I/O untuk mengakses buffer data.
Teknik berikut untuk menentukan ruang buffer tersedia:
-
Menyediakan buffer lokal.
Karena WdfIoTargetSendWriteSynchronously 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 WdfRequestRetrieveInputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input 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 dikirim WdfIoTargetSendWriteSynchronous ke target I/O telah dihapus, digunakan kembali, atau diformat ulang. (WdfIoTargetSendWriteSynchronously 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 WdfRequestRetrieveInputWdmMdl.
-
Menyediakan buffer lokal.
Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.
Untuk informasi selengkapnya tentang WdfIoTargetSendWriteSynchronously, 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, menginisialisasi struktur WDF_MEMORY_DESCRIPTOR , dan meneruskan struktur ke WdfIoTargetSendWriteSynchronously. Contoh ini menentukan NULL untuk handel objek permintaan, sehingga kerangka kerja akan membuat objek permintaan baru untuk target I/O.
WDF_MEMORY_DESCRIPTOR MemoryDescriptor;
WDFMEMORY MemoryHandle = NULL;
ULONG_PTR bytesWritten = NULL;
status = WdfMemoryCreate(
NULL,
NonPagedPool,
POOL_TAG,
MY_BUFFER_SIZE,
&MemoryHandle,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
&MemoryDescriptor,
MemoryHandle,
NULL
);
status = WdfIoTargetSendWriteSynchronously(
ioTarget,
NULL,
&MemoryDescriptor,
NULL,
NULL,
&bytesWritten
);
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 | <=PASSIVE_LEVEL |
Aturan kepatuhan DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf) |
Lihat juga
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE
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