IOCTL_BATTERY_QUERY_STATUS控制項程式碼
擷取電池的目前狀態。
若要執行這項作業，請使用下列參數呼叫 DeviceIoControl 函式。
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to battery
IOCTL_BATTERY_QUERY_STATUS, // 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_STATUS 。
-
lpInBuffer
-
BATTERY_WAIT_STATUS結構的指標。
-
nInBufferSize
-
輸入緩衝區的大小，以位元組為單位。
-
lpOutBuffer
-
BATTERY_STATUS結構的指標。
-
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
-
重迭結構的指標。
如果使用FILE_FLAG_OVERLAPPED旗標開啟hDevice，則 lpOverlapped必須指向有效的重迭結構。 在此情況下， DeviceIoControl 會以非同步 (非同步) 作業的形式執行。 如果裝置是以 FILE_FLAG_OVERLAPPED 旗標開啟， 而 lpOverlapped 為 Null，則函式會以無法預測的方式失敗。
如果 已開啟 hDevice 而不指定 FILE_FLAG_OVERLAPPED 旗標， 則會忽略 lpOverlapped ， 而且 DeviceIoControl 函式不會在作業完成之前傳回，或直到發生錯誤為止。
傳回值
如果作業順利完成， DeviceIoControl 會傳回非零值。
如果作業失敗或擱置中， DeviceIoControl 會傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
每當要求的 BatteryTag 元素不符合目前電池標籤的 BatteryTag 元素時，所有電池資訊要求的狀態都會完成ERROR_NO_SUCH_DEVICE (或ERROR_FILE_NOT_FOUND Windows 10 1809 版和更早版本) 。 這可確保傳回的電池資訊符合所要求電池 (如需詳細資訊，請參閱 電池標籤 以取得) 。
備註
此電池 IOCTL 會在作業傳回時擷取電池的狀態。 輸入參數結構 BATTERY_WAIT_STATUS，表示何時要處理並傳回電池狀態。
電池狀態的要求可以是立即傳回，也可以設定為在完成之前等候特定條件。 例如，您可以要求電池資訊，等到電池容量達到指定的點或電池狀態變更為止。
每當要求的 BatteryTag 元素不符合目前電池標籤的BatteryTag元素時，所有電池資訊要求的狀態都會完成ERROR_FILE_NOT_FOUND。 (如需詳細資訊，請參閱 電池標籤 。) 這是用來確保傳回的電池資訊符合所要求電池的電池。
如需此作業上重迭 I/O 的影響，請參閱 DeviceIoControl 主題的一節。
範例
如需範例，請參閱 列舉電池裝置。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows Server 2003 [僅限傳統型應用程式] |
| 標頭 |
|