Fungsi DeviceIoControl (ioapiset.h)
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).
- Kode Kontrol CD-ROM
- Kode Kontrol Komunikasi
- Kode Kontrol Manajemen Perangkat
- Kode Kontrol Manajemen Direktori
- Kode Kontrol Manajemen Disk
- Kode Kontrol Manajemen File
- Kode Kontrol Manajemen Daya
- Kode Kontrol Manajemen Volume
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 |