Fungsi DeviceIoControl (ioapiset.h)

Artikel
03/09/2023

Mengirim kode kontrol langsung ke driver perangkat tertentu, menyebabkan perangkat yang sesuai melakukan operasi yang sesuai.

Lihat sampel Tetapkan huruf kandar.

Sintaks

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hDevice

Handel ke perangkat tempat operasi akan dilakukan. Perangkat biasanya merupakan volume, direktori, file, atau streaming. Untuk mengambil handel perangkat, gunakan fungsi CreateFile . Untuk informasi selengkapnya, lihat Keterangan.

[in] dwIoControlCode

Kode kontrol untuk operasi. Nilai ini mengidentifikasi operasi tertentu yang akan dilakukan dan jenis perangkat untuk melakukannya.

Untuk daftar kode kontrol, lihat Keterangan. Dokumentasi untuk setiap kode kontrol menyediakan detail penggunaan untuk parameter lpInBuffer, nInBufferSize, lpOutBuffer, dan nOutBufferSize .

[in, optional] lpInBuffer

Penunjuk ke buffer input yang berisi data yang diperlukan untuk melakukan operasi. Format data ini tergantung pada nilai parameter dwIoControlCode .

Parameter ini dapat berupa NULL jika dwIoControlCode menentukan operasi yang tidak memerlukan data input.

[in] nInBufferSize

Ukuran buffer input, dalam byte.

[out, optional] lpOutBuffer

Penunjuk ke buffer output yaitu menerima data yang dikembalikan oleh operasi. Format data ini tergantung pada nilai parameter dwIoControlCode .

Parameter ini dapat berupa NULL jika dwIoControlCode menentukan operasi yang tidak mengembalikan data.

[in] nOutBufferSize

Ukuran buffer output, dalam byte.

[out, optional] lpBytesReturned

Penunjuk ke variabel yang menerima ukuran data yang disimpan dalam buffer output, dalam byte.

Jika buffer output terlalu kecil untuk menerima data apa pun, panggilan gagal, GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER, dan lpBytesReturned adalah nol.

Jika buffer output terlalu kecil untuk menyimpan semua data tetapi dapat menyimpan beberapa entri, beberapa driver akan mengembalikan data sebanyak yang cocok. Dalam hal ini, panggilan gagal, GetLastError mengembalikan ERROR_MORE_DATA, dan lpBytesReturned menunjukkan jumlah data yang diterima. Aplikasi Anda harus memanggil DeviceIoControl lagi dengan operasi yang sama, menentukan titik awal baru.

Jika lpOverlappedNULL, lpBytesReturned tidak boleh NULL. Bahkan ketika operasi tidak mengembalikan data output dan lpOutBuffer adalah NULL, DeviceIoControl menggunakan lpBytesReturned. Setelah operasi seperti itu, nilai lpBytesReturned tidak ada artinya.

Jika lpOverlapped bukan NULL, lpBytesReturned bisa NULL. Jika parameter ini bukan NULL dan operasi mengembalikan data, lpBytesReturned tidak berarti sampai operasi yang tumpang tindih telah selesai. Untuk mengambil jumlah byte yang dikembalikan, panggil GetOverlappedResult. Jika hDevice dikaitkan dengan port penyelesaian I/O, Anda dapat mengambil jumlah byte yang dikembalikan dengan memanggil GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Penunjuk ke struktur YANG TUMPANG TINDIH .

Jika hDevice dibuka tanpa menentukan FILE_FLAG_OVERLAPPED, lpOverlapped diabaikan.

Jika hDevice dibuka dengan bendera FILE_FLAG_OVERLAPPED , operasi dilakukan sebagai operasi yang tumpang tindih (asinkron). Dalam hal ini, lpOverlapped harus menunjuk ke struktur TUMPANG TINDIH yang valid yang berisi handel ke objek peristiwa. Jika tidak, fungsi gagal dengan cara yang tidak dapat diprediksi.

Untuk operasi yang tumpang tindih, DeviceIoControl segera kembali, dan objek peristiwa disinyalir ketika operasi telah selesai. Jika tidak, fungsi tidak kembali sampai operasi selesai atau terjadi kesalahan.

Mengembalikan nilai

Jika operasi berhasil diselesaikan, nilai yang dikembalikan bukan nol (TRUE).

Jika operasi gagal atau tertunda, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Untuk mengambil handel ke perangkat, Anda harus memanggil fungsi CreateFile dengan nama perangkat atau nama driver yang terkait dengan perangkat. Untuk menentukan nama perangkat, gunakan format berikut:

\\.\DeviceName

DeviceIoControl dapat menerima handel ke perangkat tertentu. Misalnya, untuk membuka handel ke drive logis A: dengan CreateFile, tentukan \\.\a:. Atau, Anda dapat menggunakan nama \\.\PhysicalDrive0, \\.\PhysicalDrive1, dan sebagainya, untuk membuka handel ke drive fisik pada sistem.

Anda harus menentukan bendera akses FILE_SHARE_READ dan FILE_SHARE_WRITE saat memanggil CreateFile untuk membuka handel ke driver perangkat. Namun, ketika Anda membuka sumber daya komunikasi, seperti port serial, Anda harus menentukan akses eksklusif. Gunakan parameter CreateFile lainnya sebagai berikut saat membuka handel perangkat:

Parameter fdwCreate harus menentukan OPEN_EXISTING.
Parameter hTemplateFile harus NULL.
Parameter fdwAttrsAndFlags dapat menentukan FILE_FLAG_OVERLAPPED untuk menunjukkan bahwa handel yang dikembalikan dapat digunakan dalam operasi I/O yang tumpang tindih (asinkron).

Untuk daftar kode kontrol yang didukung, lihat topik berikut:

Contoh

Untuk contoh yang menggunakan DeviceIoControl, lihat Memanggil DeviceIoControl.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP
Server minimum yang didukung	Windows Server 2003
Target Platform	Windows
Header	ioapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll