IOCTL_BATTERY_QUERY_INFORMATION kode kontrol
Mengambil berbagai informasi untuk baterai.
Untuk melakukan operasi ini, panggil fungsi DeviceIoControl dengan parameter berikut.
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to battery
IOCTL_BATTERY_QUERY_INFORMATION, // dwIoControlCode
(LPVOID) lpInBuffer, // input buffer
(DWORD) nInBufferSize, // size of input buffer
(LPVOID) lpOutBuffer, // output buffer
(DWORD) nOutBufferSize, // size of output buffer
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Parameter
-
hDevice
-
Handel ke baterai tempat informasi akan dikembalikan. Untuk mengambil handel perangkat, panggil fungsi CreateFile .
-
dwIoControlCode
-
Kode kontrol untuk operasi. Nilai ini mengidentifikasi operasi tertentu yang akan dilakukan dan jenis perangkat untuk melakukannya. Gunakan IOCTL_BATTERY_QUERY_INFORMATION untuk operasi ini.
-
lpInBuffer
-
Penunjuk ke struktur BATTERY_QUERY_INFORMATION .
-
nInBufferSize
-
Ukuran buffer input, dalam byte.
-
lpOutBuffer
-
Penunjuk ke buffer kembali. Jenis data (dan, oleh karena itu, ukuran) buffer pengembalian tergantung pada informasi yang diminta di anggota BATTERY_QUERY_INFORMATION_LEVEL struktur BATTERY_QUERY_INFORMATION input.
Tabel berikut ini memperlihatkan data yang dikembalikan oleh tingkat informasi tertentu.
Tingkat informasi Data dikembalikan BatteryDeviceName String Unicode yang dihentikan null yang menentukan nama baterai. BatteryEstimatedTime ULONG yang menentukan perkiraan waktu proses baterai, dalam hitung detik. Jika tingkat pengurasan yang disediakan dalam anggota AtRate dari struktur BATTERY_QUERY_INFORMATION adalah nol, perhitungan ini didasarkan pada tingkat pengurasan saat ini. Jika AtRate bukan nol, waktu yang dikembalikan adalah durasi yang diharapkan untuk tingkat yang diberikan. Jika perkiraan waktu tidak diketahui (misalnya, baterai tidak habis dan AtRate nol), BATTERY_UNKNOWN_TIME dikembalikan. Perhatikan bahwa nilai ini tidak terlalu akurat pada beberapa sistem baterai. Nilainya dapat sangat bervariasi tergantung pada penggunaan daya saat ini, yang dapat dipengaruhi oleh aktivitas disk dan faktor lainnya. Tidak ada mekanisme pemberitahuan untuk perubahan nilai ini. BatteryGranularityInformation Array panjang variabel struktur BATTERY_REPORTING_SCALE yang berisi granularitas pelaporan untuk kapasitas baterai yang dikembalikan dari IOCTL_BATTERY_QUERY_STATUS. Beberapa entri dikembalikan ketika granularitas tergantung pada kapasitas baterai saat ini. Lihat BATTERY_REPORTING_SCALE untuk interpretasi array entri. Jumlah entri ditunjukkan oleh ukuran buffer yang dikembalikan, dan dapat dihitung sebagai (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE)). Jumlah maksimum entri yang akan dikembalikan adalah empat. BatteryInformation Struktur BATTERY_INFORMATION . BatteryManufactureDate Struktur BATTERY_MANUFACTURE_DATE . BatteryManufactureName String Unicode yang dihentikan null yang berisi nama produsen baterai. BatterySerialNumber String Unicode yang dihentikan null yang berisi nomor seri baterai. BatteryTemperature ULONG yang berisi suhu baterai saat ini, dalam 10 derajat Kelvin. BatteryUniqueID String Unicode yang dihentikan null yang secara unik mengidentifikasi baterai. Nilai ini dapat digunakan untuk melacak baterai tertentu. Dalam kasus baterai pintar, ID ini akan menjadi perangkaian nama produsen, nama perangkat, tanggal pembuatan, dan representasi nomor seri yang dapat dicetak. Nilai ini tidak dimaksudkan untuk ditampilkan kepada pengguna. -
nOutBufferSize
-
Ukuran buffer output, dalam byte. Tergantung pada tingkat informasi data yang diminta, ini mungkin buffer berukuran bervariasi.
-
lpBytesReturned
-
Penunjuk ke variabel yang menerima ukuran data yang dikembalikan dalam buffer lpOutBuffer , dalam byte.
Jika buffer output terlalu kecil untuk mengembalikan data apa pun maka panggilan gagal, GetLastError mengembalikan kode kesalahan ERROR_INSUFFICIENT_BUFFER, dan jumlah byte yang dikembalikan adalah nol.
Jika lpOverlapped adalah NULL (I/O yang tidak tumpang tindih), lpBytesReturned tidak boleh NULL.
Jika lpOverlapped bukan NULL (Tumpang tindih I/O), lpBytesReturned bisa NULL. Jika ini adalah operasi yang tumpang tindih, Anda dapat mengambil jumlah byte yang dikembalikan dengan memanggil fungsi GetOverlappedResult . Jika hDevice dikaitkan dengan port penyelesaian I/O, Anda bisa mendapatkan jumlah byte yang dikembalikan dengan memanggil fungsi GetQueuedCompletionStatus .
-
lpOverlapped
-
Penunjuk ke struktur YANG TUMPANG TINDIH .
Jika hDevice dibuka dengan bendera FILE_FLAG_OVERLAPPED , lpOverlapped harus menunjuk ke struktur TUMPANG TINDIH yang valid. Dalam hal ini, DeviceIoControl dilakukan sebagai operasi yang tumpang tindih (asinkron). Jika perangkat dibuka dengan bendera FILE_FLAG_OVERLAPPED dan lpOverlapped adalah NULL, fungsi gagal dengan cara yang tidak dapat diprediksi.
Jika hDevice dibuka tanpa menentukan bendera FILE_FLAG_OVERLAPPED , lpOverlapped diabaikan dan fungsi DeviceIoControl tidak kembali sampai operasi selesai, atau sampai terjadi kesalahan.
Mengembalikan nilai
Jika operasi berhasil diselesaikan, DeviceIoControl mengembalikan nilai bukan nol.
Jika operasi gagal atau tertunda, DeviceIoControl mengembalikan nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Beberapa informasi tentang baterai bersifat opsional atau mungkin tidak berarti bagi beberapa baterai. Jika jenis data tertentu yang diminta tidak tersedia untuk baterai saat ini, maka ERROR_INVALID_FUNCTION dikembalikan.
Semua permintaan informasi baterai akan selesai dengan status ERROR_NO_SUCH_DEVICE (atau ERROR_FILE_NOT_FOUND dalam versi Windows 10 1809 dan yang lebih lama) setiap kali elemen BatteryTag permintaan tidak cocok dengan tag baterai saat ini. Ini memastikan bahwa informasi baterai yang dikembalikan cocok dengan baterai yang diminta (lihat Tag Baterai untuk informasi selengkapnya).
Keterangan
IOCTL baterai ini mengambil berbagai informasi untuk baterai. Struktur parameter input, BATTERY_QUERY_INFORMATION, menunjukkan jenis informasi yang akan dikembalikan dan kapan informasi baterai harus dikembalikan. Jenis data dan konten buffer output bervariasi berdasarkan data yang diminta.
Untuk implikasi I/O yang tumpang tindih pada operasi ini, lihat bagian Keterangan dari topik DeviceIoControl .
Contoh
Misalnya, lihat Menghitung Perangkat Baterai.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung |
Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
| Header |
|