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を返し、返されるバイト数は 0 です。

lpOverlapped が NULL (非オーバーラップ 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 要素と一致しない場合は常 Windows 10に、バッテリ情報のすべての要求がERROR_NO_SUCH_DEVICE (またはバージョン 1809 以前ではERROR_FILE_NOT_FOUND) の状態で完了します。 これにより、返されたバッテリー情報が要求されたバッテリーの情報と一致します (詳細については、「 バッテリー タグ 」を参照してください)。

注釈

このバッテリ IOCTL は、バッテリの現在のタグを取得します。 バッテリ タグは、物理的なバッテリが再挿入、交換、または特性の変更を受けたときに変化する一意の 0 以外の値です。 バッテリー タグがいつ変更されるか、変更を検出する方法、およびバッテリ タグの変更後にアプリケーションを続行する方法の詳細については、「バッテリー 情報 の概要」トピックの「バッテリー タグ」セクションを参照してください。 バッテリが存在しない場合、この要求は指定された時刻を待機し、バッテリーがまだ存在しない場合は、 ERROR_FILE_NOT_FOUND に戻り、バッテリー タグを BATTERY_TAG_INVALIDに設定します。 (詳細については、「バッテリー情報」を参照してください)。

他のバッテリー情報に対するすべての要求では、呼び出し元が一致するバッテリー タグを指定する必要があります。 これにより、呼び出し元が要求ごとに同じバッテリの情報を受信し、呼び出し元が一定のポーリングなしでバッテリの変更を認識するようになります。

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

例

例については、「 Battery Devices の列挙」を参照してください。

要件

要件 値
サポートされている最小のクライアント
 Windows XP [デスクトップ アプリのみ]
サポートされている最小のサーバー
 Windows Server 2003 [デスクトップ アプリのみ]
Header
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