共用方式為


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,而傳回的位元組計數為零。

如果 lpOverlappedNull (非重迭 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 旗標開啟, 而 lpOverlappedNull,則函式會以無法預測的方式失敗。

如果 已開啟 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 [僅限傳統型應用程式]
標頭
Poclass.h;
Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP 上的 BatClass.h

另請參閱

電池資訊

電源管理控制程式代碼

DeviceIoControl

BATTERY_STATUS

BATTERY_WAIT_STATUS

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_TAG

IOCTL_BATTERY_SET_INFORMATION