コントロール コードの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エラー コードを返し、返されるバイト数は 0 です。

lpOverlapped が NULL (非overlapped I/O) の場合、lpBytesReturned を NULL にすることはできません。

lpOverlapped が NULL (重複した I/O) でない場合、lpBytesReturned は NULL にすることができます。 重複する操作の場合は、 GetOverlappedResult 関数を呼び出して返されるバイト数を取得できます。 hDevice が I/O 入力候補ポートに関連付けられている場合は、GetQueuedCompletionStatus 関数を呼び出すことによって返されるバイト数を取得できます。

lpOverlapped

OVERLAPPED 構造体へのポインター。

hDevice が FILE_FLAG_OVERLAPPED フラグで開かれた場合、lpOverlapped は有効な OVERLAPPED 構造体を指す必要があります。 この場合、 DeviceIoControl は重複した (非同期) 操作として実行されます。 デバイスが FILE_FLAG_OVERLAPPED フラグで開き、 lpOverlapped が NULL の場合、予期しない方法で関数が失敗します。

FILE_FLAG_OVERLAPPED フラグを指定せずに hDevice を開いた場合、lpOverlapped は無視され、操作が完了するまで、またはエラーが発生するまで DeviceIoControl 関数は返されません。

戻り値

操作が正常に完了すると、 DeviceIoControl は 0 以外の値を返します。

操作が失敗した場合、または保留中の場合、 DeviceIoControl は 0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

要求の BatteryTag 要素が現在のバッテリ タグの BatteryTag 要素と一致しない場合は常に、バッテリー情報に関するすべての要求がERROR_NO_SUCH_DEVICE (またはバージョン 1809 以前Windows 10 ERROR_FILE_NOT_FOUND) の状態で完了します。 これにより、返されたバッテリ情報が要求されたバッテリの情報と一致します (詳細については、「 バッテリー タグ 」を参照してください)。

注釈

このバッテリー IOCTL は、操作が戻った時点のバッテリーの状態を取得します。 入力パラメーター構造 BATTERY_WAIT_STATUSは、バッテリの状態をいつ処理して返すのか示します。

バッテリーの状態の要求は、すぐに戻る場合や、完了する前に特定の条件を待機するように設定できます。 たとえば、バッテリ容量が指定したポイントに達するか、バッテリの状態が変化するまで待機するバッテリ情報の要求を行うことができます。

要求の BatteryTag 要素が 現在のバッテリ タグの BatteryTag 要素と一致しない場合は常に、バッテリー情報に関するすべての要求がERROR_FILE_NOT_FOUNDの状態で完了します。 (詳細については、「 バッテリー タグ 」を参照してください)。これは、返されたバッテリ情報が要求されたバッテリの情報と一致することを確認するために使用されます。

この操作に対する重複した I/O の影響については、 DeviceIoControl トピックの「解説」セクションを参照してください。

例

例については、「 バッテリ デバイスの列挙」を参照してください。

要件

こちらもご覧ください

バッテリー情報

電源管理コントロール コード

DeviceIoControl

BATTERY_STATUS

BATTERY_WAIT_STATUS

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_TAG

IOCTL_BATTERY_SET_INFORMATION