WdfIoTargetSendInternalIoctlOthersSynchronously function (wdfiotarget.h)
[Berlaku untuk KMDF saja]
Metode WdfIoTargetSendInternalIoctlOthersSynchronously membangun permintaan kontrol perangkat internal non-standar dan mengirimkannya secara sinkron ke target I/O.
Sintaks
NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg1,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg2,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg4,
[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 berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in] IoctlCode
Kode kontrol I/O (IOCTL) yang didukung target I/O.
[in, optional] OtherArg1
Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang menjelaskan buffer memori yang berisi informasi konteks. Parameter ini bersifat opsional dan dapat berupa NULL.
[in, optional] OtherArg2
Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang menjelaskan buffer memori yang berisi informasi konteks. Parameter ini bersifat opsional dan dapat berupa NULL.
[in, optional] OtherArg4
Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang menjelaskan buffer memori yang berisi informasi konteks. Parameter ini bersifat opsional dan dapat berupa 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, lihat bagian Keterangan 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 berupa NULL.
Nilai kembali
Jika operasi berhasil, WdfIoTargetSendInternalIoctlOthersSynchronously 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:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Ukuran struktur WDF_REQUEST_SEND_OPTIONS yang ditujukan parameter RequestOptions salah. |
|
Permintaan 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
Permintaan kontrol perangkat internal non-standar menggunakan kode IOCTL untuk mengidentifikasi operasi yang akan dilakukan, tetapi permintaan tidak menggunakan buffer input dan output standar yang digunakan permintaan kontrol perangkat internal lainnya. Jika Anda membuat sekumpulan driver yang berinteraksi, Anda dapat menentukan bagaimana kumpulan driver ini menggunakan argumen permintaan: OtherArg1, OtherArg2, dan OtherArg4.
Tidak ada parameter yang disebut OtherArg3 karena kerangka kerja mengaitkan parameter ini dengan anggota Argument1, Argument2, dan Argument4 dari union Other.Parameters dalam struktur IO_STACK_LOCATION driver. Anggota Argumen3 dalam serikat tersebut menerima nilai dari parameter IoctlCode , sehingga tidak tersedia untuk nilai yang disediakan driver lainnya.
Gunakan metode WdfIoTargetSendInternalIoctlOthersSynchronously untuk mengirim permintaan kontrol perangkat internal non-standar secara sinkron. Untuk mengirim permintaan kontrol perangkat internal secara asinkron, gunakan WdfIoTargetFormatRequestForInternalIoctlOthers, diikuti oleh WdfRequestSend.
Untuk informasi selengkapnya tentang permintaan kontrol perangkat internal, lihat Menggunakan Kode Kontrol I/O.
Metode WdfIoTargetSendInternalIoctlOthersSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS parameter RequestOptions, atau kecuali kesalahan terdeteksi.
Anda dapat meneruskan permintaan kontrol perangkat internal non-standar 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 mungkin beberapa ruang konteks.
Untuk meneruskan permintaan kontrol perangkat internal non-standar yang diterima driver Anda dalam antrean I/O:
- Tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfIoTargetSendInternalIoctlOthersSynchronously.
-
Gunakan informasi konteks permintaan yang diterima untuk parameter WdfIoTargetSendInternalIoctlOthersSynchronously metode OtherArg1,OtherArg2, danOtherArg4.
Untuk mendapatkan nilai parameter ini, driver harus memanggil WdfRequestGetParameters dan menggunakan anggota DeviceIoControl dari struktur WDF_REQUEST_PARAMETERS yang dikembalikan.
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 Permintaanmetode WdfIoTargetSendInternalIoctlOthersSynchronously, 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.
-
Sediakan ruang konteks untuk parameter OtherArg1, OtherArg2, dan OtherArg4 metode WdfIoTargetSendInternalIoctlOthersSynchronously, jika permintaan memerlukannya.
Driver Anda dapat menentukan ruang konteks 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.
Teknik berikut untuk menentukan ruang buffer tersedia:
-
Menyediakan buffer lokal.
Karena WdfIoTargetSendInternalIoctlOthersSynchronously 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);
-
Menyediakan MDL.
Driver dapat memperoleh MDL yang terkait dengan permintaan I/O yang diterima dengan memanggil WdfRequestRetrieveInputWdmMdl dan WdfRequestRetrieveOutputWdmMdl.
-
Menyediakan buffer lokal.
Untuk informasi selengkapnya tentang WdfIoTargetSendInternalIoctlOthersSynchronously, 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 menginisialisasi struktur IEEE 1394 IRB, menggunakan alamat struktur untuk menginisialisasi struktur WDF_MEMORY_DESCRIPTOR , lalu memanggil WdfIoTargetSendInternalIoctlOthersSynchronously.
WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;
Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&descriptor,
&Irb,
sizeof (IRB)
);
ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
IoTarget,
NULL,
IOCTL_1394_CLASS,
&descriptor,
NULL,
NULL,
NULL,
NULL
);
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | 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) |
Lihat juga
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfIoTargetFormatRequestForInternalIoctlOthers
WdfRequestCompleteWithInformation
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