src/Tizen.System/Device/Battery.cs

   1 /*
   2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the License);
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an AS IS BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 using System;
  18
  19 namespace Tizen.System
  20 {
  21     /// <summary>
  22     /// Enumeration for the battery levels.
  23     /// </summary>
  24     /// <since_tizen> 3 </since_tizen>
  25     public enum BatteryLevelStatus
  26     {
  27         /// <summary>
  28         /// The battery goes empty.
  29         /// Prepare for the safe termination of the application,
  30         /// because the device starts a shutdown process soon
  31         /// after entering this level.
  32         /// </summary>
  33         /// <since_tizen> 3 </since_tizen>
  34         Empty = 0,
  35         /// <summary>
  36         /// The battery charge is at a critical state.
  37         /// You may have to stop using the multimedia features,
  38         /// because they are not guaranteed to work correctly
  39         /// with this battery status.
  40         /// </summary>
  41         /// <since_tizen> 3 </since_tizen>
  42         Critical,
  43         /// <summary>
  44         /// The battery has little charge left.
  45         /// </summary>
  46         /// <since_tizen> 3 </since_tizen>
  47         Low,
  48         /// <summary>
  49         /// The battery status is not to be careful.
  50         /// </summary>
  51         /// <since_tizen> 3 </since_tizen>
  52         High,
  53         /// <summary>
  54         /// The battery status is fully charged.
  55         /// It means no more charge.
  56         /// </summary>
  57         /// <since_tizen> 3 </since_tizen>
  58         Full
  59     }
  60
  61     /// <summary>
  62     /// The Battery class provides the properties and events for the device battery.
  63     /// </summary>
  64     /// <remarks>
  65     /// The Battery API provides the way to get the current battery capacity value (Percent),
  66     /// the battery state, and the charging state. It also provides the events for an application
  67     /// to receive the battery status change events from the device.
  68     /// To receive the battery event, the application should register with the respective EventHandler.
  69     /// </remarks>
  70     /// <code>
  71     ///     Console.WriteLine("battery Charging state is: {0}", Tizen.System.Battery.IsCharging);
  72     ///     Console.WriteLine("battery Percent is: {0}", Tizen.System.Battery.Percent);
  73     /// </code>
  74     public static class Battery
  75     {
  76         private static readonly object s_lock = new object();
  77         /// <summary>
  78         /// Gets the battery charge percentage.
  79         /// </summary>
  80         /// <since_tizen> 3 </since_tizen>
  81         /// <value>It returns an integer value from 0 to 100 that indicates the remaining
  82         /// battery charge as a percentage of the maximum level.</value>
  83         public static int Percent
  84         {
  85             get
  86             {
  87                 int percent = 0;
  88                 DeviceError res = (DeviceError)Interop.Device.DeviceBatteryGetPercent(out percent);
  89                 if (res != DeviceError.None)
  90                 {
  91                     Log.Warn(DeviceExceptionFactory.LogTag, "unable to get battery percentage.");
  92                 }
  93                 return percent;
  94             }
  95         }
  96         /// <summary>
  97         /// Gets the current battery level.
  98         /// </summary>
  99         /// <since_tizen> 3 </since_tizen>
 100         public static BatteryLevelStatus Level
 101         {
 102             get
 103             {
 104                 int level = 0;
 105                 DeviceError res = (DeviceError)Interop.Device.DeviceBatteryGetLevelStatus(out level);
 106                 if (res != DeviceError.None)
 107                 {
 108                     Log.Warn(DeviceExceptionFactory.LogTag, "unable to get battery status.");
 109                 }
 110                 return (BatteryLevelStatus)level;
 111             }
 112         }
 113         /// <summary>
 114         /// Gets the current charging state.
 115         /// </summary>
 116         /// <since_tizen> 3 </since_tizen>
 117         public static bool IsCharging
 118         {
 119             get
 120             {
 121                 bool charging;
 122                 DeviceError res = (DeviceError)Interop.Device.DeviceBatteryIsCharging(out charging);
 123                 if (res != DeviceError.None)
 124                 {
 125                     Log.Warn(DeviceExceptionFactory.LogTag, "unable to get battery charging state.");
 126                 }
 127                 return charging;
 128             }
 129         }
 130
 131         private static EventHandler<BatteryPercentChangedEventArgs> s_capacityChanged;
 132         /// <summary>
 133         /// CapacityChanged is triggered when the battery charge percentage is changed.
 134         /// </summary>
 135         /// <since_tizen> 3 </since_tizen>
 136         /// <param name="sender"></param>
 137         /// <param name="e">BatteryCapacityChangedEventArgs is an object that contains the changed battery capacity (Percent).</param>
 138         /// <code>
 139         /// public static async Task BatteryEventHandler()
 140         /// {
 141         ///     EventHandler<BatteryPercentChangedEventArgs> handler = null;
 142         ///     handler = (object sender, BatteryChargingStateChangedEventArgs args) =>
 143         ///     {
 144         ///          Console.WriteLine("battery Percent is: {0}", args.Percent);
 145         ///     }
 146         ///     Battery.PercentChanged += handler;
 147         ///     await Task.Delay(20000);
 148         ///  }
 149         /// </code>
 150         public static event EventHandler<BatteryPercentChangedEventArgs> PercentChanged
 151         {
 152             add
 153             {
 154                 lock (s_lock)
 155                 {
 156                     if (s_capacityChanged == null)
 157                     {
 158                         EventListenerStart(EventType.BatteryPercent);
 159                     }
 160                     s_capacityChanged += value;
 161                 }
 162             }
 163             remove
 164             {
 165                 lock (s_lock)
 166                 {
 167                     s_capacityChanged -= value;
 168                     if (s_capacityChanged == null)
 169                     {
 170                         EventListenerStop(EventType.BatteryPercent);
 171                     }
 172                 }
 173             }
 174         }
 175
 176         private static event EventHandler<BatteryLevelChangedEventArgs> s_levelChanged;
 177
 178         /// <summary>
 179         /// LevelChanged is triggered when the battery level is changed.
 180         /// </summary>
 181         /// <since_tizen> 3 </since_tizen>
 182         /// <param name="sender"></param>
 183         /// <param name="e">BatteryLevelChangedEventArgs is an object that contains the changed battery level.</param>
 184         /// <code>
 185         /// public static async Task BatteryEventHandler()
 186         /// {
 187         ///     EventHandler<BatteryLevelChangedEventArgs> handler = null;
 188         ///     handler = (object sender, BatteryLevelChangedEventArgs args) =>
 189         ///     {
 190         ///          Console.WriteLine("battery Level is: {0}", args.Level);
 191         ///     }
 192         ///     Battery.LevelChanged += handler;
 193         ///     await Task.Delay(20000);
 194         ///  }
 195         /// </code>
 196         public static event EventHandler<BatteryLevelChangedEventArgs> LevelChanged
 197         {
 198             add
 199             {
 200                 lock (s_lock)
 201                 {
 202                     if (s_levelChanged == null)
 203                     {
 204                         EventListenerStart(EventType.BatteryLevel);
 205                     }
 206                     s_levelChanged += value;
 207                 }
 208             }
 209             remove
 210             {
 211                 lock (s_lock)
 212                 {
 213                     s_levelChanged -= value;
 214                     if (s_levelChanged == null)
 215                     {
 216                         EventListenerStop(EventType.BatteryLevel);
 217                     }
 218                 }
 219             }
 220         }
 221
 222         private static event EventHandler<BatteryChargingStateChangedEventArgs> s_chargingStateChanged;
 223         /// <summary>
 224         /// ChargingStatusChanged is triggered when the battery charging status is changed.
 225         /// This event is triggered when the charger is connected/disconnected.
 226         /// </summary>
 227         /// <since_tizen> 3 </since_tizen>
 228         /// <param name="sender"></param>
 229         /// <param name="e">BatteryChargingStateChangedEventArgs is an object that contains the changed battery charging state.</param>
 230         /// <code>
 231         /// public static async Task BatteryEventHandler()
 232         /// {
 233         ///     EventHandler<BatteryChargingStateChangedEventArgs> handler = null;
 234         ///     handler = (object sender, BatteryChargingStateChangedEventArgs args) =>
 235         ///     {
 236         ///          Console.WriteLine("battery Level is: {0}", args.IsCharging);
 237         ///     }
 238         ///     Battery.ChargingStateChanged += handler;
 239         ///     await Task.Delay(20000);
 240         ///  }
 241         /// </code>
 242         public static event EventHandler<BatteryChargingStateChangedEventArgs> ChargingStateChanged
 243         {
 244             add
 245             {
 246                 lock (s_lock)
 247                 {
 248                     if (s_chargingStateChanged == null)
 249                     {
 250                         EventListenerStart(EventType.BatteryCharging);
 251                     }
 252                     s_chargingStateChanged += value;
 253                 }
 254             }
 255             remove
 256             {
 257                 lock (s_lock)
 258                 {
 259                     s_chargingStateChanged -= value;
 260                     if (s_chargingStateChanged == null)
 261                     {
 262                         EventListenerStop(EventType.BatteryCharging);
 263                     }
 264                 }
 265             }
 266         }
 267
 268         private static Interop.Device.deviceCallback s_cpacityHandler;
 269         private static Interop.Device.deviceCallback s_levelHandler;
 270         private static Interop.Device.deviceCallback s_chargingHandler;
 271
 272         private static void EventListenerStart(EventType eventType)
 273         {
 274             switch (eventType)
 275             {
 276                 case EventType.BatteryPercent:
 277                     s_cpacityHandler = (int type, IntPtr value, IntPtr data) =>
 278                     {
 279                         int val = value.ToInt32();
 280                         BatteryPercentChangedEventArgs e = new BatteryPercentChangedEventArgs()
 281                         {
 282                             Percent = val
 283                         };
 284                         s_capacityChanged?.Invoke(null, e);
 285                         return true;
 286                     };
 287
 288                     Interop.Device.DeviceAddCallback(eventType, s_cpacityHandler, IntPtr.Zero);
 289                     break;
 290
 291                 case EventType.BatteryLevel:
 292                     s_levelHandler = (int type, IntPtr value, IntPtr data) =>
 293                     {
 294                         int val = value.ToInt32();
 295                         BatteryLevelChangedEventArgs e = new BatteryLevelChangedEventArgs()
 296                         {
 297                             Level = (BatteryLevelStatus)val
 298                         };
 299                         s_levelChanged?.Invoke(null, e);
 300                         return true;
 301                     };
 302
 303                     Interop.Device.DeviceAddCallback(eventType, s_levelHandler, IntPtr.Zero);
 304                     break;
 305
 306                 case EventType.BatteryCharging:
 307                     s_chargingHandler = (int type, IntPtr value, IntPtr data) =>
 308                     {
 309                         bool val = (value.ToInt32() == 1);
 310                         BatteryChargingStateChangedEventArgs e = new BatteryChargingStateChangedEventArgs()
 311                         {
 312                             IsCharging = val
 313                         };
 314                         s_chargingStateChanged?.Invoke(null, e);
 315                         return true;
 316                     };
 317                     Interop.Device.DeviceAddCallback(eventType, s_chargingHandler, IntPtr.Zero);
 318                     break;
 319             }
 320         }
 321
 322         private static void EventListenerStop(EventType eventType)
 323         {
 324             switch (eventType)
 325             {
 326                 case EventType.BatteryPercent:
 327                     Interop.Device.DeviceRemoveCallback(eventType, s_cpacityHandler);
 328                     break;
 329
 330                 case EventType.BatteryLevel:
 331                     Interop.Device.DeviceRemoveCallback(eventType, s_levelHandler);
 332                     break;
 333
 334                 case EventType.BatteryCharging:
 335                     Interop.Device.DeviceRemoveCallback(eventType, s_chargingHandler);
 336                     break;
 337             }
 338         }
 339     }
 340 }