Symbian3/SDK/Source/GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita
changeset 7 51a74ef9ed63
parent 0 89d6a7a84779
equal deleted inserted replaced
6:43e37759235e 7:51a74ef9ed63
       
     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&amp;S) power state
       
    15 keys that are updated by HWRM server. </p>
       
    16 <p>The P&amp;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&amp;S API, refer to the <xref href="GUID-A81C65CF-CF4E-571C-8080-9D387F46AAD6.dita">Publish
       
    21 and Subscribe documentation</xref>. </p>
       
    22 <p>P&amp;S is used by HW Resource Manager to globally publish the power state
       
    23 information. The P&amp;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&amp;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&amp;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&amp;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&amp;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&amp;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&amp;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>