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