IOCTL_BATTERY_QUERY_INFORMATION コントロール コード

バッテリーのさまざまな情報を取得します。

この操作を実行するには、次のパラメーターを使用して DeviceIoControl 関数を呼び出します。

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to battery
  IOCTL_BATTERY_QUERY_INFORMATION, // 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_INFORMATION を使用します。

lpInBuffer

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

nInBufferSize

入力バッファーのサイズ (バイト単位)。

lpOutBuffer

戻りバッファーへのポインター。 戻りバッファーのデータ型 (およびそのため、サイズ) は、入力BATTERY_QUERY_INFORMATION構造体のBATTERY_QUERY_INFORMATION_LEVEL メンバーで要求された情報によって異なります。

次の表は、特定の情報レベルによって返されるデータを示しています。

情報レベル	返されるデータ
BatteryDeviceName	バッテリーの名前を指定する Null で終わる Unicode 文字列。
BatteryEstimatedTime	バッテリーの推定実行時間を秒単位で指定する ULONG 。 BATTERY_QUERY_INFORMATION構造体の AtRate メンバーに設けられたドレインの速度が 0 の場合、この計算はドレインの現在のレートに基づいています。 AtRate が 0 以外の場合、返される時間は、指定されたレートに対して予想される実行時間です。 推定時間が不明な場合 (たとえば、バッテリが放電せず、 AtRate が 0 の場合) 、BATTERY_UNKNOWN_TIME が返されます。 この値は、一部のバッテリ システムでは非常に正確ではないことに注意してください。 この値は、現在の電力使用量によって大きく異なる場合があります。これは、ディスクアクティビティやその他の要因の影響を受ける可能性があります。 この値の変更に関する通知メカニズムはありません。
BatteryGranularityInformation	IOCTL_BATTERY_QUERY_STATUSから返されるバッテリ容量のレポート粒度を含む、BATTERY_REPORTING_SCALE構造体の可変長配列。 粒度がバッテリーの現在の容量に依存すると、複数のエントリが返されます。 エントリの配列の解釈については、「 BATTERY_REPORTING_SCALE 」を参照してください。 エントリの数は、返されるバッファーのサイズによって示され、 (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE)) として計算できます。 返されるエントリの最大数は 4 です。
BatteryInformation	BATTERY_INFORMATION構造体。
BatteryManufactureDate	BATTERY_MANUFACTURE_DATE構造体。
BatteryManufactureName	バッテリの製造元の名前を含む Null で終わる Unicode 文字列。
BatterySerialNumber	バッテリのシリアル番号を含む Null で終わる Unicode 文字列。
BatteryTemperature	バッテリーの現在の温度を 10 分の 1 ケルビン単位で格納する ULONG 。
BatteryUniqueID	バッテリーを一意に識別する Null で終わる Unicode 文字列。 この値は、特定のバッテリーを追跡するために使用できます。 スマート バッテリーの場合、この ID は製造元の名前、デバイス名、製造日、およびシリアル番号の印刷可能な表現を連結したものです。 この値は、ユーザーに表示されるものではありません。

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 を呼び出します。

電池に関する一部の情報はオプションであり、一部の電池では意味がない場合があります。 要求された特定の種類のデータが現在のバッテリで使用できない場合は、 ERROR_INVALID_FUNCTION が返されます。

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

注釈

このバッテリ IOCTL は、バッテリーのさまざまな情報を取得します。 入力パラメーター構造体 BATTERY_QUERY_INFORMATIONは、返される情報の種類と、バッテリ情報を返すタイミングを示します。 出力バッファーのデータ型と内容は、要求されたデータによって異なります。

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

例

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

要件

こちらもご覧ください

バッテリー情報

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

DeviceIoControl

BATTERY_QUERY_INFORMATION

BATTERY_REPORTING_SCALE

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_QUERY_TAG

IOCTL_BATTERY_SET_INFORMATION