WdfIoTargetSendInternalIoctlSynchronously function (wdfiotarget.h)

Artikel
07/16/2024

[Hanya berlaku untuk KMDF]

Metode WdfIoTargetSendInternalIoctlSynchronously membangun permintaan kontrol perangkat internal dan mengirimkannya secara sinkron ke target I/O.

Sintaksis

NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

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 NULL. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini.

[in] IoctlCode

Kode kontrol I/O (IOCTL) yang didukung target I/O.

[in, optional] InputBuffer

Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang dialokasikan pemanggil yang menjelaskan buffer yang akan ditulis ke target I/O. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini. Parameter ini bersifat opsional dan dapat NULL jika permintaan tidak mengirim data.

[in, optional] OutputBuffer

Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang dialokasikan pemanggil yang menjelaskan buffer yang akan menerima data dari target I/O. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini. Parameter ini bersifat opsional dan dapat NULL jika permintaan tidak menerima data.

[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.

[out, optional] BytesReturned

Pointer ke lokasi yang menerima informasi (seperti jumlah byte yang ditransfer) yang disediakan driver lain ketika menyelesaikan permintaan dengan memanggil WdfRequestCompleteWithInformation. Penunjuk ini bersifat opsional dan dapat NULL.

Mengembalikan nilai

Jika operasi berhasil, WdfIoTargetSendInternalIoctlSynchronously kembali setelah permintaan kontrol perangkat internal selesai, dan nilai yang dikembalikan adalah nilai status penyelesaian permintaan. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Mengembalikan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_REQUEST_SEND_OPTIONS yang ditujukan oleh parameter RequestOptions salah.
STATUS_INVALID_DEVICE_REQUEST	Permintaan sudah diantrekan ke target I/O.
STATUS_INSUFFICIENT_RESOURCES	Kerangka kerja tidak dapat mengalokasikan sumber daya sistem (biasanya memori).
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 WdfIoTargetSendInternalIoctlSynchronously untuk mengirim permintaan kontrol perangkat internal secara sinkron. Untuk mengirim permintaan kontrol perangkat internal secara asinkron, gunakan metode WdfIoTargetFormatRequestForInternalIoctl, diikuti dengan metode WdfRequestSend.

Untuk informasi selengkapnya tentang permintaan kontrol perangkat internal, lihat Menggunakan Kode Kontrol I/O.

Metode WdfIoTargetSendInternalIoctlSynchronously 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 kontrol perangkat internal 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 kontrol perangkat internal yang diterima driver Anda dalam antrean I/O:

Tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfIoTargetSendInternalIoctlSynchronous ly.
Gunakan buffer input permintaan yang diterima untuk parameter WdfIoTargetSendInternalIoctlSynchronously metode InputBuffer.
Driver harus memanggil WdfRequestRetrieveInputMemory untuk mendapatkan handel ke buffer input permintaan. Driver kemudian harus menempatkan handel tersebut dalam struktur WDF_MEMORY_DESCRIPTOR yang disediakan driver untuk parameter InputBuffer.
Gunakan buffer output permintaan yang diterima untuk parameter WdfIoTargetSendInternalIoctlSynchronously metode OutputBuffer.
Driver harus memanggil WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke buffer output permintaan, dan kemudian harus menempatkan handel tersebut dalam struktur WDF_MEMORY_DESCRIPTOR yang disediakan driver untuk parameter OutputBuffer .

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
untuk WdfIoTargetSendInternalIoctlSynchronously 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 WdfIoTargetSendInternalIoctlSynchronously metode InputBuffer dan OutputBuffer, jika permintaan memerlukannya.
Driver Anda dapat menentukan ruang buffer ini sebagai buffer yang dialokasikan secara lokal, seperti yang ditangani WDFMEMORY, atau sebagai daftar deskriptor memori (MDL). Anda dapat menggunakan metode mana pun yang paling nyaman.

Jika perlu, kerangka kerja mengonversi deskripsi buffer sehingga benar untuk jenis transfer IOCTL. Untuk informasi selengkapnya tentang jenis transfer IOCTL, lihat Menentukan Kode Kontrol I/O.

Teknik berikut untuk menentukan ruang buffer tersedia:
- Sediakan buffer lokal.
  Karena WdfIoTargetSendInternalIoctlSynchronously 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 atau WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer 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 WdfIoTargetSendInternalIoctlSynchronously dikirim ke target I/O telah dihapus, digunakan kembali, atau diformat ulang. (WdfIoTargetSendInternalIoctlSynchronously 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 dan WdfRequestRetrieveOutputWdmMdl.

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

Untuk informasi selengkapnya tentang WdfIoTargetSendInternalIoctlSynchronously, 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 mendefinisikan buffer lokal, menginisialisasi struktur WDF_MEMORY_DESCRIPTOR, dan memanggil WdfIoTargetSendInternalIoctlSynchronously. Contoh ini menentukan NULL untuk handel objek permintaan, sehingga kerangka kerja akan membuat objek permintaan baru untuk target I/O.

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
MY_DRIVER_INFORMATION  driverInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &driverInformation,
                                  sizeof(MY_DRIVER_INFORMATION)
                                  );

status = WdfIoTargetSendInternalIoctlSynchronously(
                                                   hidTarget,
                                                   NULL,
                                                   IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
                                                   NULL,
                                                   &outputDescriptor,
                                                   NULL,
                                                   NULL
                                                   );

Persyaratan

Syarat	Nilai
Platform Target	Universal
versi KMDF Minimum	1.0
Header	wdfiotarget.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	PASSIVE_LEVEL
aturan kepatuhan DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf)), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)