IOCTL_BATTERY_QUERY_TAG控制項程式碼
擷取電池目前的標記。
若要執行這項作業，請使用下列參數呼叫 DeviceIoControl 函式。
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to battery
IOCTL_BATTERY_QUERY_TAG, // 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_TAG 。
-
lpInBuffer
-
ULONG輸入緩衝區的指標。 值表示沒有電池時要等候的毫秒數。 值 -1 表示要求會無限期地等候 (，或直到某些其他事件取消為止) 。
-
nInBufferSize
-
輸入緩衝區的大小，以位元組為單位。
-
lpOutBuffer
-
ULONG輸出緩衝區的指標。 在成功時，此緩衝區包含目前的電池標記，除了BATTERY_TAG_INVALID之外，它可以是任何值。 失敗時，如果 GetLastError 傳回錯誤碼 ERROR_FILE_NOT_FOUND，此緩衝區會包含值 BATTERY_TAG_INVALID。
-
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 會擷取電池目前的標籤。 電池標記是唯一的非零值，會在實體電池重新插入、取代或經歷任何特性變更時變更。 如需電池標籤變更、如何偵測變更，以及應用程式在電池標籤變更後應如何繼續進行的詳細資訊，請參閱電池 資訊 概觀主題中的電池標記一節。 當電池不存在時，此要求會等候指定的時間，如果仍然沒有電池存在，則會傳回 ERROR_FILE_NOT_FOUND ，並將電池標記設定為 BATTERY_TAG_INVALID。 (如需詳細資訊，請參閱電池資訊。)
其他電池資訊的所有要求都需要呼叫端提供相符的電池標籤。 這可確保呼叫端收到每個要求相同電池的資訊，並確保呼叫端知道電池變更，而不需持續輪詢。
如需此作業上重迭 I/O 的影響，請參閱 DeviceIoControl 主題的一節。
範例
如需範例，請參閱 列舉電池裝置。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows Server 2003 [僅限傳統型應用程式] |
| 標頭 |
|