Share via

IOCTL_BATTERY_QUERY_INFORMATION控制項程式碼

  • 發行項

擷取電池的各種資訊。

若要執行這項作業，請使用下列參數呼叫 DeviceIoControl 函 式。

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
);

參數

hDevice

要傳回信息的電池控制碼。 若要擷取裝置控制碼，請呼叫 CreateFile 函式。

dwIoControlCode

作業的控制程式代碼。 這個值會識別要執行的特定作業，以及要在其中執行的裝置類型。 使用此作業 IOCTL_BATTERY_QUERY_INFORMATION 。

lpInBuffer

BATTERY_QUERY_INFORMATION結構的指標。

nInBufferSize

輸入緩衝區的大小，以位元組為單位。

lpOutBuffer

傳回緩衝區的指標。 資料類型 (，因此傳回緩衝區的大小) 取決於輸入BATTERY_QUERY_INFORMATION結構BATTERY_QUERY_INFORMATION_LEVEL成員中所要求的資訊。

下表顯示指定資訊層級所傳回的資料。

資訊層級 傳回的資料
BatteryDeviceName 以 Null結尾的 Unicode 字串，指定電池的名稱。
BatteryEstimatedTime ULONG，指定預估的電池執行時間，以秒為單位。 如果BATTERY_QUERY_INFORMATION結構之AtRate成員中提供的清空率為零，則此計算是以目前的清空率為基礎。 如果 AtRate 為非零，傳回的時間會是指定速率的預期執行時間。 例如，如果估計時間未知 (，則電池不會放開，而 AtRate 為零) ，則會傳回 BATTERY_UNKNOWN_TIME 。 請注意，在某些電池系統上，這個值並不精確。 根據目前的電源使用量，此值可能會有很大的差異，這可能會受到磁片活動和其他因素的影響。 這個值沒有變更的通知機制。
BatteryGranularityInformation BATTERY_REPORTING_SCALE 結構的可變 長度陣列，其中包含從 IOCTL_BATTERY_QUERY_STATUS傳回之電池容量的報告細微性。 當細微性取決於電池的目前容量時，會傳回多個專案。 如需專案陣列的解譯，請參閱 BATTERY_REPORTING_SCALE 。 專案數目會以傳回的緩衝區大小表示，而且可以計算為 (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE) ) 。 將傳回的專案數目上限為四。
BatteryInformation BATTERY_INFORMATION結構。
BatteryManufactureDate BATTERY_MANUFACTURE_DATE結構。
BatteryManufactureName 以 Null終止的 Unicode 字串，其中包含電池製造商的名稱。
BatterySerialNumber 以 Null終止的 Unicode 字串，其中包含電池的序號。
BatteryTemperature ULONG，包含電池目前溫度，以 Kelvin 度 10 秒為單位。
BatteryUniqueID 以 Null終止的 Unicode 字串，可唯一識別電池。 這個值可用來追蹤特定的電池。 在智慧電池的情況下，此識別碼將是製造商名稱、裝置名稱、製造日期，以及可列印的序號標記法。 此值並非要向使用者顯示。

nOutBufferSize

輸出緩衝區的大小 (以位元組為單位)。 視所要求的資料資訊層級而定，這可能是可變大小的緩衝區。

lpBytesReturned

變數的指標，接收 lpOutBuffer 緩衝區中傳回的資料大小，以位元組為單位。

如果輸出緩衝區太小而無法傳回任何資料，則呼叫會失敗， GetLastError 會傳回錯誤碼 ERROR_INSUFFICIENT_BUFFER，而傳回的位元組計數為零。

如果 lpOverlapped 是 Null (非重迭 I/O) ， 則 lpBytesReturned 不可為 Null。

如果 lpOverlapped 不是 Null (重迭的 I/O) ， lpBytesReturned 可以是 Null。 如果這是重迭的作業，您可以呼叫 GetOverlappedResult 函式來擷取傳回的位元組數目。 如果 hDevice 與 I/O 完成埠相關聯，您可以呼叫 GetQueuedCompletionStatus 函式來取得傳回的位元組數目。

lpOverlapped

重迭結構的指標。

如果 hDevice 是以 FILE_FLAG_OVERLAPPED 旗標開啟， lpOverlapped 必須指向有效的 OVERLAPPED 結構。 在此情況下， DeviceIoControl 會以重迭的 (非同步) 作業來執行。 如果裝置以 FILE_FLAG_OVERLAPPED 旗標開啟，且 lpOverlapped 為 Null，則函式會以無法預期的方式失敗。

如果在未指定FILE_FLAG_OVERLAPPED旗標的情況下開啟hDevice，則會忽略lpOverlapped，而且DeviceIoControl函式不會在作業完成或發生錯誤之前傳回。

傳回值

如果作業順利完成， DeviceIoControl 會傳回非零值。

如果作業失敗或擱置中， DeviceIoControl 會 傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

某些電池的相關資訊是選擇性的，或對於某些電池而言可能沒有意義。 如果目前電池無法使用所要求的特定資料類型，則會傳回 ERROR_INVALID_FUNCTION 。

每當要求的 BatteryTag 元素不符合目前電池標籤的 BatteryTag 元素時，Windows 10 1809 版和) 更早版本中的所有電池資訊要求都會完成狀態ERROR_NO_SUCH_DEVICE (或ERROR_FILE_NOT_FOUND。 這可確保傳回的電池資訊符合所要求電池 (如需詳細資訊，請參閱 電池標籤) 。

備註

此電池 IOCTL 會擷取電池的各種資訊。 輸入參數結構 BATTERY_QUERY_INFORMATION會指出要傳回的資訊類型，以及何時應該傳回電池資訊。 輸出緩衝區的資料類型和內容會根據所要求的資料而有所不同。

如需此作業上重迭 I/O 的影響，請參閱 DeviceIoControl 主題的一節。

範例

如需範例，請參閱 列舉電池裝置。

規格需求

需求 值
最低支援的用戶端
 Windows XP [僅限傳統型應用程式]
最低支援的伺服器
 Windows Server 2003 [僅限桌面應用程式]
標頭
Poclass.h;
Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP 上的 BatClass.h

另請參閱

電池資訊

電源管理控制程式代碼

DeviceIoControl

BATTERY_QUERY_INFORMATION

BATTERY_REPORTING_SCALE

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_QUERY_TAG

IOCTL_BATTERY_SET_INFORMATION