1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122
  123
  124
  125
  126
  127
  128
  129
  130
  131


base / power_monitor / battery_level_provider.h [blame]

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_
#define BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_

#include <stdint.h>

#include <memory>
#include <optional>
#include <vector>

#include "base/functional/callback.h"
#include "base/time/time.h"
#include "build/build_config.h"

namespace base {

// BatteryLevelProvider provides an interface for querying battery state.
// A platform specific implementation is obtained with
// BatteryLevelProvider::Create().
class BASE_EXPORT BatteryLevelProvider {
 public:
  // The possible units of data used for the battery level.
  enum class BatteryLevelUnit {
    // Milliwatt-hour. This is desired as it is more precise.
    kMWh,
    // Milliampere-hour. Used when the capacity in ampere-hour is available but
    // not the voltage to convert to milliwatt-hour. Prefer mWh if available.
    kMAh,
    // Relative occurs when Windows returns imprecise battery counters.
    kRelative,
  };

  // Represents an aggregated state of all the batteries on the system at a
  // certain point in time.
  struct BatteryState {
    // Number of batteries on the system.
    int battery_count = 0;

    // Whether the system is connected to an external source of power. Defaults
    // to `true` if `battery_count` is 0.
    bool is_external_power_connected = false;

    // Current battery capacity. nullopt if `battery_count` != 1.
    std::optional<uint64_t> current_capacity;

    // Fully charged battery capacity. nullopt if `battery_count` != 1.
    std::optional<uint64_t> full_charged_capacity;

    // The voltage of the battery. Only available on MacOS. nullopt if
    // `battery_count` != 1.
    std::optional<uint64_t> voltage_mv;

    // The unit of the battery's charge. Usually kMWh (milliwatt-hour) but can
    // be relative on Windows. nullopt if `battery_count` != 1.
    std::optional<BatteryLevelUnit> charge_unit;

    // The time at which the battery state capture took place.
    base::TimeTicks capture_time;

#if BUILDFLAG(IS_WIN)
    // The granularity of the battery discharge. Always the most coarse
    // granularity among all the reporting scales of the battery, regardless of
    // the current capacity, in milliwatt-hours. Only available on
    // Windows, and if a battery is present. This value is populated by the
    // manufacturer and is not guaranteed to be available or accurate.
    std::optional<uint32_t> battery_discharge_granularity;
#endif  // BUILDFLAG(IS_WIN)
  };

  // Creates a platform specific BatteryLevelProvider able to retrieve battery
  // state.
  static std::unique_ptr<BatteryLevelProvider> Create();

  virtual ~BatteryLevelProvider() = default;

  BatteryLevelProvider(const BatteryLevelProvider& other) = delete;
  BatteryLevelProvider& operator=(const BatteryLevelProvider& other) = delete;

  // Queries the current battery state and forwards it to `callback` when ready
  // (forwards nullopt on retrieval error). `callback` will not be invoked if
  // the BatteryLevelProvider is destroyed.
  virtual void GetBatteryState(
      base::OnceCallback<void(const std::optional<BatteryState>&)>
          callback) = 0;

 protected:
  BatteryLevelProvider() = default;

  struct BatteryDetails {
    // Whether the battery is connected to an external power source.
    bool is_external_power_connected;

    // The current battery capacity.
    uint64_t current_capacity;

    // The battery's fully charged capacity.
    uint64_t full_charged_capacity;

    // The voltage of the battery. Only available on MacOS.
    std::optional<uint64_t> voltage_mv;

    // The battery's unit of charge.
    BatteryLevelUnit charge_unit;

#if BUILDFLAG(IS_WIN)
    // The granularity of the |current_capacity| value, in hundredths of a
    // percent. Only available on Windows, and if a battery is present. This
    // value is populated by the manufacturer and is not guaranteed to be
    // available or accurate.
    std::optional<uint32_t> battery_discharge_granularity;

    // The most coarse granularity among all the reporting scales of the
    // battery, in hundredths of a percent. Only available on Windows, and if a
    // battery is present. This value is populated by the manufacturer and is
    // not guaranteed to be available or accurate.
    std::optional<uint32_t> max_battery_discharge_granularity;
#endif  // BUILDFLAG(IS_WIN)
  };

  // Constructs a `BatteryState` from a list of `BatteryDetails`. The list can
  // be empty if there are no batteries on the system.
  static BatteryState MakeBatteryState(
      const std::vector<BatteryDetails>& battery_details);
};

}  // namespace base

#endif  // BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_