Merge "Update deprecated libprivilege-control API functions." into tizen
[platform/framework/native/appfw.git] / inc / FSysBattery.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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 /**
18  * @if OSPCOMPAT
19  * @file        FSysBattery.h
20  * @brief       This is the header file for the %Battery class.
21  *
22  * This header file contains the declarations of the %Battery class.
23  * @endif
24  */
25
26 #ifndef _FSYS_BATTERY_H_
27 #define _FSYS_BATTERY_H_
28
29 #include <FBaseObject.h>
30 #include <FSysPowerManager.h>
31
32 namespace Tizen { namespace System
33 {
34
35 /**
36  * @if OSPCOMPAT
37  * @class       Battery
38  * @brief       <i>[Deprecated]</i> This class provides methods to get information related to the battery charge.
39  *
40  * @since       2.0
41  *
42  * @deprecated  This class is deprecated. Instead of using this class, use the PowerManager class.
43  * @final       This class is not intended for extension.
44  *
45  * The %Battery class provides methods to get the status related to battery levels and determine whether the battery is 
46  * currently being charged. You cannot create an instance of this class directly.
47  *
48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/battery_status.htm">Battery Status</a>.
49  * @endif
50  */
51
52 class _OSP_EXPORT_ Battery
53         : public Tizen::Base::Object
54 {
55
56 public:
57         /**
58          * @cond OSPDEPREC
59          * Gets the current charge remaining in the battery as a percentage.
60          *
61          * @deprecated  This method is deprecated. Instead of using this method, use the PowerManager::GetCurrentBatteryLevelInPercentage() method.
62          * @since       2.0
63          * @if OSPCOMPAT
64          * @brief       <i>[Deprecated] [Compatibility] </i>
65          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
66          *                                      For more information, see @ref CompGetCurrentLevelInPercentage "here".
67          * @endif
68          * @return              An error code
69          * @param[out]  level                   The percentage of the charge remaining in the battery
70          * @exception   E_SUCCESS               The method is successful.
71          * @exception   E_INVALID_STATE The battery service is not available.
72          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
73          * @remarks     The resolution of the level is @c 1% since 2.0. The range of the level is @c 0 (Minimum) to @c 100 (Maximum).
74          * @endcond
75          */
76         static result GetCurrentLevelInPercentage(int& level);
77
78         /**
79          * @if OSPCOMPAT
80          * @page        CompGetCurrentLevelInPercentage Compatibility for current battery level
81          * @section     CompGetCurrentLevelInPercentageIssue Issues
82          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
83          *
84          * - GetCurrentLevelInPercentage() is moved to PowerManager class.
85          *
86          * @section     CompGetCurrentLevelInPercentageResolution Resolutions
87          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
88          *
89          * - GetCurrentLevelInPercentage() is provided by PowerManager class.
90          * @endif
91          */
92
93         /**
94          * @cond OSPDEPREC
95          * Gets the current charging level of the battery.
96          *
97          * @deprecated  This method is deprecated. Instead of using this method, use the PowerManager::GetCurrentBatteryLevel() method.
98          * @since       2.0
99          * @if OSPCOMPAT
100          * @brief       <i>[Deprecated] [Compatibility] </i>
101          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
102          *                                      For more information, see @ref CompGetCurrentLevel "here".
103          * @endif
104          * @return              An error code
105          * @param[out]  level           A value from the enumerator BatteryLevel indicating the current charging level
106          * @exception   E_SUCCESS               The method is successful.
107          * @exception   E_INVALID_STATE The battery service is not available.
108          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
109          * @endcond
110          */
111         static result GetCurrentLevel(BatteryLevel& level);
112
113         /**
114          * @if OSPCOMPAT
115          * @page        CompGetCurrentLevel Compatibility for current battery level
116          * @section     CompGetCurrentLevelIssue Issues
117          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
118          *
119          * - CompGetCurrentLevel() is moved to PowerManager class.
120          *
121          * @section     CompGetCurrentLevelResolution Resolutions
122          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
123          *
124          * - GetCurrentLevel() is supported by PowerManager class.
125          * @endif
126          */
127
128         /**
129          * @cond OSPDEPREC
130          * Checks whether the battery is currently charging.
131          *
132          * @deprecated  This method is deprecated. Instead of using this method, use the PowerManager::IsCharging() method.
133          * @since       2.0
134          * @if OSPCOMPAT
135          * @brief       <i>[Deprecated] [Compatibility] </i>
136          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
137          *                                      For more information, see @ref CompIsCharging "here".
138          * @endif
139          * @return      An error code
140          * @param[out]  charging        Set to @c true if the charging cable is connected to the phone, @n
141          *                                                      else @c false
142          * @exception   E_SUCCESS               The method is successful.
143          * @exception   E_INVALID_STATE The battery service is not available.
144          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
145          * @endcond
146          */
147         static result IsCharging(bool& charging);
148
149         /**
150          * @if OSPCOMPAT
151          * @page        CompIsCharging Compatibility for current battery level
152          * @section     CompIsChargingIssue Issues
153          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
154          *
155          * - IsCharging() is moved to PowerManager class.
156          *
157          * @section     CompIsChargingResolution Resolutions
158          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
159          *
160          * - IsCharging() is supported by PowerManager class.
161          * @endif
162          */
163
164 private:
165         /**
166          * This is the default constructor for this class. This default constructor is intentionally declared as private so that only the platform can create an instance.
167          */
168         Battery(void);
169
170         /**
171          * This is the destructor for this class. 
172          * This destructor overrides Tizen::Base::Object::~Object(). @n
173          */
174         virtual ~Battery(void);
175
176         /**
177          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
178          */
179         Battery(const Battery& value);
180
181         /**
182          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
183          */
184         Battery& operator =(const Battery& value);
185
186 private:
187         friend class _BatteryImpl;
188 }; // Battery
189
190 } } // Tizen::System
191
192 #endif // _FSYS_BATTERY_H_