|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E" xml:lang="en"><title>Power |
|
13 State API</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Power State API provides the Publish and Subscribe (P&S) power state |
|
15 keys that are updated by HWRM server. </p> |
|
16 <p>The P&S power state keys provide up-to-date information on the charging |
|
17 status, battery level and battery state of the device. Any application may |
|
18 subscribe to these keys that are updated to receive notifications for any |
|
19 change in state. This interface is provided by three Publish and Subscribe |
|
20 keys. For details on using the P&S API, refer to the <xref href="GUID-A81C65CF-CF4E-571C-8080-9D387F46AAD6.dita">Publish |
|
21 and Subscribe documentation</xref>. </p> |
|
22 <p>P&S is used by HW Resource Manager to globally publish the power state |
|
23 information. The P&S UID is <codeph>KPSUidHWRMPowerState</codeph> and |
|
24 provides the following keys: </p> |
|
25 <ul> |
|
26 <li id="GUID-B0F5D317-6B63-52C0-85A8-EC30053866BB"><p><xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-576EAE06-666F-5903-B006-EA923B7000B5">KHWRMBatteryLevel</xref> </p> </li> |
|
27 <li id="GUID-5E41F5AE-C3C2-54AA-8959-0A90E4785E90"><p><xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-5C7D4483-D58A-522B-8B38-D30117698381">KHWRMBatteryStatus</xref> </p> </li> |
|
28 <li id="GUID-A3C5C6AF-EDB6-5EFD-A713-802F6E8A8DD7"><p><xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-C4B24C0C-762F-5319-90B9-5BE8C8E94ABC">KHWRMChargingStatus</xref> </p> </li> |
|
29 </ul> |
|
30 <section id="GUID-576EAE06-666F-5903-B006-EA923B7000B5"><title>KHWRMBatteryLevel</title> <p>P&S |
|
31 key to represent the battery level of the device. It also relates to the number |
|
32 of battery bars displayed. This property is updated only when battery level |
|
33 changes. Valid values are defined by the <codeph>EPSHWRMBatteryLevel</codeph> enumeration |
|
34 and ranges from -1 to 7. </p> <p>If an error occurs or the battery level is |
|
35 not initialized, the enumeration value of <codeph>EBatteryLevelUnknown</codeph> is |
|
36 used. In all other scenarios, the battery level is used with level 0 being |
|
37 the lowest (battery empty) and level 7 the highest (battery full). </p> <p>Refer |
|
38 to the <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-CD1197EA-3FDF-53A5-B808-F01F18468121">Keys</xref> and <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-AC5B84A9-1393-5473-8C87-A226CFDB6544">Enumerations</xref> section |
|
39 for more information. </p> </section> |
|
40 <section id="GUID-5C7D4483-D58A-522B-8B38-D30117698381"><title>KHWRMBatteryStatus</title> <p>P&S |
|
41 key to represent the battery status of the device. For example, <b>Uninitialized</b>, <b>Ok</b>, <b>Low</b>, <b>Empty</b>. |
|
42 This property may be updated to same status as previously, to indicate that |
|
43 the note in question must be displayed again. </p> <p> <codeph>EPSHWRMBatteryStatus</codeph> enumeration |
|
44 defines the valid values as shown in the following table: </p> <table id="GUID-A339E622-0E97-5020-94A8-18DAED60D8C3"> |
|
45 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
46 <thead> |
|
47 <row> |
|
48 <entry>EPSHWRMBatteryStatus</entry> |
|
49 <entry>Description</entry> |
|
50 </row> |
|
51 </thead> |
|
52 <tbody> |
|
53 <row> |
|
54 <entry><p> <codeph>EBatteryStatusUnknown</codeph> </p> </entry> |
|
55 <entry><p>Battery status is unknown or some error has occurred in retrieving |
|
56 the battery status. </p> </entry> |
|
57 </row> |
|
58 <row> |
|
59 <entry><p> <codeph>EBatteryStatusOk</codeph> </p> </entry> |
|
60 <entry><p>Battery level is normal. </p> </entry> |
|
61 </row> |
|
62 <row> |
|
63 <entry><p> <codeph>EBatteryStatusLow</codeph> </p> </entry> |
|
64 <entry><p>Battery level is low, and the user can be notified with a message |
|
65 warning them that battery is low. This value is updated approximately ten |
|
66 times before battery is completely empty and updated comes at approximately |
|
67 10-minute intervals. If phone is in-call mode, update comes at approximately |
|
68 1-minute intervals. </p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p> <codeph>EBatteryStatusEmpty</codeph> </p> </entry> |
|
72 <entry><p>Battery level is empty. This value is updated slightly before the |
|
73 phone must be powered down automatically because of insufficient battery power. </p> </entry> |
|
74 </row> |
|
75 </tbody> |
|
76 </tgroup> |
|
77 </table> <p>Refer to the <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-CD1197EA-3FDF-53A5-B808-F01F18468121">Keys</xref> and <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-AC5B84A9-1393-5473-8C87-A226CFDB6544">Enumerations</xref> section |
|
78 for more information. </p> </section> |
|
79 <section id="GUID-C4B24C0C-762F-5319-90B9-5BE8C8E94ABC"><title>KHWRMChargingStatus</title> <p>P&S |
|
80 key to represent the charging status of the device. For example, <b>Charging</b>, <b>NotCharging</b>, <b>ChargingComplete</b>. |
|
81 This property is updated only when charging status changes. </p> <p> <codeph>EPSHWRMChargingStatus</codeph> enumeration |
|
82 defines the valid values as shown in the following table: </p> <table id="GUID-EE9B5750-B531-5AE4-8FA3-6997105CDB72"> |
|
83 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
84 <thead> |
|
85 <row> |
|
86 <entry>EPSHWRMChargingStatus</entry> |
|
87 <entry>Description</entry> |
|
88 </row> |
|
89 </thead> |
|
90 <tbody> |
|
91 <row> |
|
92 <entry><p> <codeph>EChargingStatusError</codeph> </p> </entry> |
|
93 <entry><p>An error occurred when the charger is connected to the device. </p> </entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><p> <codeph>EChargingStatusNotConnected</codeph> </p> </entry> |
|
97 <entry><p>A charger has not been connected to the device. This also represents |
|
98 the uninitialized value if no charger has been initialized. </p> </entry> |
|
99 </row> |
|
100 <row> |
|
101 <entry><p> <codeph>EChargingStatusCharging</codeph> </p> </entry> |
|
102 <entry><p>Charger is connected to the device and charging is ongoing. </p> </entry> |
|
103 </row> |
|
104 <row> |
|
105 <entry><p> <codeph>EChargingStatusNotCharging</codeph> </p> </entry> |
|
106 <entry><p>Charger is connected to the device but the device is not charging, |
|
107 for example, due to battery being full. </p> </entry> |
|
108 </row> |
|
109 <row> |
|
110 <entry><p> <codeph>EChargingStatusAlmostComplete</codeph> </p> </entry> |
|
111 <entry><p>Device is charging and the battery is almost full. </p> </entry> |
|
112 </row> |
|
113 <row> |
|
114 <entry><p> <codeph>EChargingStatusChargingComplete</codeph> </p> </entry> |
|
115 <entry><p>Charging has just been completed, and hence a notification may be |
|
116 shown to the user if required. </p> </entry> |
|
117 </row> |
|
118 <row> |
|
119 <entry><p> <codeph>EChargingStatusChargingContinued</codeph> </p> </entry> |
|
120 <entry><p>Special case where charging was interrupted briefly but is now continuing, |
|
121 for example, when a dynamo type of charger is used. </p> </entry> |
|
122 </row> |
|
123 </tbody> |
|
124 </tgroup> |
|
125 </table> <p>Refer to the <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-CD1197EA-3FDF-53A5-B808-F01F18468121">Keys</xref> and <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita#GUID-16A42EB3-4F45-5623-9981-1DEE3234471E/GUID-AC5B84A9-1393-5473-8C87-A226CFDB6544">Enumerations</xref> section |
|
126 for more information. </p> </section> |
|
127 <section id="GUID-CD1197EA-3FDF-53A5-B808-F01F18468121"><title>Keys </title> <table id="GUID-99D595A4-685F-5ABA-A684-4AB137368F10"> |
|
128 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
129 <thead> |
|
130 <row> |
|
131 <entry> Keys </entry> |
|
132 <entry>Valid Values</entry> |
|
133 <entry> Description </entry> |
|
134 </row> |
|
135 </thead> |
|
136 <tbody> |
|
137 <row> |
|
138 <entry><p> <codeph>KHWRMBatteryLevel</codeph> </p> </entry> |
|
139 <entry><p>0x00000001 </p> </entry> |
|
140 <entry><p>P&S key representing battery level of device. </p> </entry> |
|
141 </row> |
|
142 <row> |
|
143 <entry><p> <codeph>KHWRMBatteryStatus</codeph> </p> </entry> |
|
144 <entry><p>0x00000002 </p> </entry> |
|
145 <entry><p>P&S key representing battery status of device. </p> </entry> |
|
146 </row> |
|
147 <row> |
|
148 <entry><p> <codeph>KHWRMChargingStatus</codeph> </p> </entry> |
|
149 <entry><p>0x00000003 </p> </entry> |
|
150 <entry><p>P&S key representing charging status of device. </p> </entry> |
|
151 </row> |
|
152 </tbody> |
|
153 </tgroup> |
|
154 </table> </section> |
|
155 <section id="GUID-AC5B84A9-1393-5473-8C87-A226CFDB6544"><title> Enumerations</title> <p> <b>Battery |
|
156 level of device</b> </p> <p>Interpreted as <codeph>EPSHWRMBatteryLevel</codeph> enumeration |
|
157 and can be related to the number of battery bars displayed by the device. </p> <table id="GUID-9DB20436-D945-5363-9089-1B312FE2AD86"> |
|
158 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
159 <thead> |
|
160 <row> |
|
161 <entry> EPSHWRMBatteryLevel </entry> |
|
162 <entry>Valid Values</entry> |
|
163 <entry> Description </entry> |
|
164 </row> |
|
165 </thead> |
|
166 <tbody> |
|
167 <row> |
|
168 <entry><p> <codeph>EBatteryLevelUnknown</codeph> </p> </entry> |
|
169 <entry><p>-1 </p> </entry> |
|
170 <entry><p>Uninitialized or some other error. </p> </entry> |
|
171 </row> |
|
172 <row> |
|
173 <entry><p> <codeph>EBatteryLevelLevel0</codeph> </p> </entry> |
|
174 <entry><p>0</p> </entry> |
|
175 <entry><p>Lowest battery level. </p> </entry> |
|
176 </row> |
|
177 <row> |
|
178 <entry><p> <codeph>EBatteryLevelLevel1</codeph> </p> </entry> |
|
179 <entry><p>1</p> </entry> |
|
180 <entry><p>Battery Level 1. </p> </entry> |
|
181 </row> |
|
182 <row> |
|
183 <entry><p> <codeph>EBatteryLevelLevel2</codeph> </p> </entry> |
|
184 <entry><p>2</p> </entry> |
|
185 <entry><p>Battery Level 2. </p> </entry> |
|
186 </row> |
|
187 <row> |
|
188 <entry><p> <codeph>EBatteryLevelLevel3</codeph> </p> </entry> |
|
189 <entry><p>3</p> </entry> |
|
190 <entry><p>Intermediate levels </p> </entry> |
|
191 </row> |
|
192 <row> |
|
193 <entry><p> <codeph>EBatteryLevelLevel4</codeph> </p> </entry> |
|
194 <entry><p>4</p> </entry> |
|
195 <entry><p>Battery Level 4. </p> </entry> |
|
196 </row> |
|
197 <row> |
|
198 <entry><p> <codeph>EBatteryLevelLevel5</codeph> </p> </entry> |
|
199 <entry><p>5</p> </entry> |
|
200 <entry><p>Battery Level 5. </p> </entry> |
|
201 </row> |
|
202 <row> |
|
203 <entry><p> <codeph>EBatteryLevelLevel6</codeph> </p> </entry> |
|
204 <entry><p>6</p> </entry> |
|
205 <entry><p>Battery Level 6. </p> </entry> |
|
206 </row> |
|
207 <row> |
|
208 <entry><p> <codeph>EBatteryLevelLevel7</codeph> </p> </entry> |
|
209 <entry><p>7</p> </entry> |
|
210 <entry><p>Highest battery level. </p> </entry> |
|
211 </row> |
|
212 </tbody> |
|
213 </tgroup> |
|
214 </table> <p> <b>Battery status of device</b> </p> <p>Interpreted as <codeph>EPSHWRMBatteryStatus</codeph> enumeration |
|
215 and can be related to the battery status of the device. </p> <table id="GUID-E8331299-6047-579D-B4AD-8DF3B0C7028E"> |
|
216 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
217 <thead> |
|
218 <row> |
|
219 <entry> EPSHWRMBatteryStatus </entry> |
|
220 <entry>Valid Values</entry> |
|
221 <entry> Description </entry> |
|
222 </row> |
|
223 </thead> |
|
224 <tbody> |
|
225 <row> |
|
226 <entry><p> <codeph>EBatteryStatusUnknown</codeph> </p> </entry> |
|
227 <entry><p>-1 </p> </entry> |
|
228 <entry><p> <systemoutput>Uninitialized</systemoutput> or some other error. </p> </entry> |
|
229 </row> |
|
230 <row> |
|
231 <entry><p> <codeph>EBatteryStatusOk</codeph> </p> </entry> |
|
232 <entry><p>0</p> </entry> |
|
233 <entry><p>This can also be used during charging. </p> </entry> |
|
234 </row> |
|
235 <row> |
|
236 <entry><p> <codeph>EBatteryStatusLow</codeph> </p> </entry> |
|
237 <entry><p>1</p> </entry> |
|
238 <entry><p>Show "<systemoutput>Battery low</systemoutput> " note to user . </p> </entry> |
|
239 </row> |
|
240 <row> |
|
241 <entry><p> <codeph>EBatteryStatusEmpty</codeph> </p> </entry> |
|
242 <entry><p>2</p> </entry> |
|
243 <entry><p>Show "<systemoutput>Recharge battery</systemoutput> " note to user. </p> </entry> |
|
244 </row> |
|
245 </tbody> |
|
246 </tgroup> |
|
247 </table> <p> <b>Charging status of device</b> </p> <p>Interpreted as enumeration <codeph>EPSHWRMChargingStatus</codeph> and |
|
248 can be related to the charging status of the device. </p> <table id="GUID-1BC438C0-8110-53C7-9F4E-77060CFE9202"> |
|
249 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
250 <thead> |
|
251 <row> |
|
252 <entry> EPSHWRMChargingStatus </entry> |
|
253 <entry>Valid Values</entry> |
|
254 <entry> Description </entry> |
|
255 </row> |
|
256 </thead> |
|
257 <tbody> |
|
258 <row> |
|
259 <entry><p> <codeph>EChargingStatusError</codeph> </p> </entry> |
|
260 <entry><p>-1 </p> </entry> |
|
261 <entry><p>Some error has occurred when charger is connected or charging. </p> </entry> |
|
262 </row> |
|
263 <row> |
|
264 <entry><p> <codeph>EChargingStatusNotConnected</codeph> </p> </entry> |
|
265 <entry><p>0</p> </entry> |
|
266 <entry><p>Charger uninitialized or not connected. </p> </entry> |
|
267 </row> |
|
268 <row> |
|
269 <entry><p> <codeph>EChargingStatusCharging</codeph> </p> </entry> |
|
270 <entry><p>1</p> </entry> |
|
271 <entry><p>Device is charging. </p> </entry> |
|
272 </row> |
|
273 <row> |
|
274 <entry><p> <codeph> EChargingStatusNotCharging</codeph> </p> </entry> |
|
275 <entry><p>2</p> </entry> |
|
276 <entry><p>Charger is connected, device not charging. </p> </entry> |
|
277 </row> |
|
278 <row> |
|
279 <entry><p> <codeph>EChargingStatusAlmostComplete</codeph> </p> </entry> |
|
280 <entry><p>3</p> </entry> |
|
281 <entry><p>Charging almost completed. </p> </entry> |
|
282 </row> |
|
283 <row> |
|
284 <entry><p> <codeph>EChargingStatusChargingComplete</codeph> </p> </entry> |
|
285 <entry><p>4</p> </entry> |
|
286 <entry><p>Charging completed. </p> </entry> |
|
287 </row> |
|
288 <row> |
|
289 <entry><p> <codeph>EChargingStatusChargingContinued</codeph> </p> </entry> |
|
290 <entry><p>5</p> </entry> |
|
291 <entry><p>Charging continued after brief interruption. </p> </entry> |
|
292 </row> |
|
293 </tbody> |
|
294 </tgroup> |
|
295 </table> </section> |
|
296 </conbody><related-links> |
|
297 <link href="GUID-C3B6E5F6-74DC-5C0E-94C8-B4822F4A2EB6.dita"><linktext>Power State |
|
298 API Tutorial</linktext></link> |
|
299 </related-links></concept> |