1 // Copyright 2020 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_ 6 #define BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_ 7 8 #include <stdint.h> 9 #include <memory> 10 #include <vector> 11 12 #include "base/functional/callback.h" 13 #include "base/time/time.h" 14 #include "build/build_config.h" 15 #include "third_party/abseil-cpp/absl/types/optional.h" 16 17 namespace base { 18 19 // BatteryLevelProvider provides an interface for querying battery state. 20 // A platform specific implementation is obtained with 21 // BatteryLevelProvider::Create(). 22 class BASE_EXPORT BatteryLevelProvider { 23 public: 24 // The possible units of data used for the battery level. 25 enum class BatteryLevelUnit { 26 // Milliwatt-hour. This is desired as it is more precise. 27 kMWh, 28 // Milliampere-hour. Used when the capacity in ampere-hour is available but 29 // not the voltage to convert to milliwatt-hour. Prefer mWh if available. 30 kMAh, 31 // Relative occurs when Windows returns imprecise battery counters. 32 kRelative, 33 }; 34 35 // Represents an aggregated state of all the batteries on the system at a 36 // certain point in time. 37 struct BatteryState { 38 // Number of batteries on the system. 39 int battery_count = 0; 40 41 // Whether the system is connected to an external source of power. Defaults 42 // to `true` if `battery_count` is 0. 43 bool is_external_power_connected = false; 44 45 // Current battery capacity. nullopt if `battery_count` != 1. 46 absl::optional<uint64_t> current_capacity; 47 48 // Fully charged battery capacity. nullopt if `battery_count` != 1. 49 absl::optional<uint64_t> full_charged_capacity; 50 51 // The voltage of the battery. Only available on MacOS. nullopt if 52 // `battery_count` != 1. 53 absl::optional<uint64_t> voltage_mv; 54 55 // The unit of the battery's charge. Usually kMWh (milliwatt-hour) but can 56 // be relative on Windows. nullopt if `battery_count` != 1. 57 absl::optional<BatteryLevelUnit> charge_unit; 58 59 // The time at which the battery state capture took place. 60 base::TimeTicks capture_time; 61 62 #if BUILDFLAG(IS_WIN) 63 // The granularity of the battery discharge. Always the most coarse 64 // granularity among all the reporting scales of the battery, regardless of 65 // the current capacity, in milliwatt-hours. Only available on 66 // Windows, and if a battery is present. This value is populated by the 67 // manufacturer and is not guaranteed to be available or accurate. 68 absl::optional<uint32_t> battery_discharge_granularity; 69 #endif // BUILDFLAG(IS_WIN) 70 }; 71 72 // Creates a platform specific BatteryLevelProvider able to retrieve battery 73 // state. 74 static std::unique_ptr<BatteryLevelProvider> Create(); 75 76 virtual ~BatteryLevelProvider() = default; 77 78 BatteryLevelProvider(const BatteryLevelProvider& other) = delete; 79 BatteryLevelProvider& operator=(const BatteryLevelProvider& other) = delete; 80 81 // Queries the current battery state and forwards it to `callback` when ready 82 // (forwards nullopt on retrieval error). `callback` will not be invoked if 83 // the BatteryLevelProvider is destroyed. 84 virtual void GetBatteryState( 85 base::OnceCallback<void(const absl::optional<BatteryState>&)> 86 callback) = 0; 87 88 protected: 89 BatteryLevelProvider() = default; 90 91 struct BatteryDetails { 92 // Whether the battery is connected to an external power source. 93 bool is_external_power_connected; 94 95 // The current battery capacity. 96 uint64_t current_capacity; 97 98 // The battery's fully charged capacity. 99 uint64_t full_charged_capacity; 100 101 // The voltage of the battery. Only available on MacOS. 102 absl::optional<uint64_t> voltage_mv; 103 104 // The battery's unit of charge. 105 BatteryLevelUnit charge_unit; 106 107 #if BUILDFLAG(IS_WIN) 108 // The granularity of the |current_capacity| value, in hundredths of a 109 // percent. Only available on Windows, and if a battery is present. This 110 // value is populated by the manufacturer and is not guaranteed to be 111 // available or accurate. 112 absl::optional<uint32_t> battery_discharge_granularity; 113 114 // The most coarse granularity among all the reporting scales of the 115 // battery, in hundredths of a percent. Only available on Windows, and if a 116 // battery is present. This value is populated by the manufacturer and is 117 // not guaranteed to be available or accurate. 118 absl::optional<uint32_t> max_battery_discharge_granularity; 119 #endif // BUILDFLAG(IS_WIN) 120 }; 121 122 // Constructs a `BatteryState` from a list of `BatteryDetails`. The list can 123 // be empty if there are no batteries on the system. 124 static BatteryState MakeBatteryState( 125 const std::vector<BatteryDetails>& battery_details); 126 }; 127 128 } // namespace base 129 130 #endif // BASE_POWER_MONITOR_BATTERY_LEVEL_PROVIDER_H_ 131