Share via

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

另請參閱

電池資訊

電源管理控制程式代碼

DeviceIoControl

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_SET_INFORMATION