IOCTL_BATTERY_QUERY_INFORMATION kode kontrol

Artikel
06/12/2023

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	Poclass.h; BatClass.h pada Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP

Lihat juga

Informasi Baterai
Kode Kontrol Manajemen Daya
DeviceIoControl
BATTERY_QUERY_INFORMATION
BATTERY_REPORTING_SCALE
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION

Share via