--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../css/snippet.css" />
+ <script type="text/javascript" src="../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/search.js" charset="utf-8"></script>
+
+ <title>Power Manager Sample Overview</title>
+</head>
+
+<body class="no-toc" onload="prettyPrint()" style="overflow: auto;">
+
+<div id="toc-navigation">
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+ <div id="profile">
+ <p><img alt="Mobile native" src="../images/mobile_s_n.png"/></p>
+ </div>
+
+<h1>Power Manager Sample Overview</h1>
+
+<p>The sample demonstrates how to use System and App Control API to monitor and change device's settings (battery level, screen brightness, Wi-Fi, GPS, Bluetooth).</p>
+
+<p>The Power Manager sample application implements three following features:</p>
+<ul>
+ <li>
+ <p><u>Displaying device information</u></p>
+ <p>The panel at the top of the screen displays battery percentage and level (empty/critical/low/high), charging status (on/off) as well as the status of
+ some power consuming device's settings (Wi-Fi, Bluetooth, GPS).</p>
+ </li>
+ <li>
+ <p><u>Warning the user when the battery level drops too low</u></p>
+ <p>When the battery level drops below the defined warnings level, a popup is displayed to warn the user about it (Fig. 2). The user can manually set the warnings level.</p>
+ </li>
+ <li>
+ <p><u>Enabling/disabling custom Power Saving mode</u></p>
+ <p>The application provides a convenient way to change the following device's settings to reduce power consumption:</p>
+ <ul>
+ <li>display brightness - when in Power Saving mode, the display brightness is changed to low (20%);</li>
+ <li>Wi-Fi state - when in Power Saving mode, the Wi-Fi is automatically turned off;</li>
+ <li>Bluetooth state - when in Power Saving mode, the user will be advised to turn off Bluetooth and, upon request, Settings application will be launched;</li>
+ <li>GPS state - approach same as in the Bluetooth state case.</li>
+ </ul>
+ <p>When the Power Saving mode is disabled, display brightness is changed to full (100%) and the power consuming settings can be turned on the same way they were turned off
+ (whether automatically or upon request).</p>
+ <p>There are 3 types of alerts the user can encounter when trying to turn Power Saving mode on/off:</p>
+ <ul>
+ <li>turn power consuming settings off - if the application detects that any of the three power consuming settings (Wi-Fi, Bluetooth or GPS) is on when enabling Power Saving mode,
+ a popup is displayed to alert the user about it (Fig. 4) and offers to launch Settings application to manage it;</li>
+ <li>turn power consuming settings on - similarly, if the application detects that any of the three settings is off when disabling Power Saving mode,
+ a popup is displayed (Fig. 5);</li>
+ <li>device is charging - Power Saving mode will not be enabled if the device is charging. If the user tries to turn the mode on in such situation, a popup
+ is displayed to inform the user about it (Fig. 6).</li>
+ </ul>
+ </li>
+</ul>
+
+<table>
+<col/>
+<tr>
+ <td>
+ <p class="figure">Figure 1: Power Manager sample app main view.</p>
+ <p align="center"><img alt="Power Manager sample app main view" src="../images/power_manager_main_view.png" border="1"/></p>
+ </td>
+ <td>
+ <p class="figure">Figure 2: Power Manager sample app view: battery level dropped.</p>
+ <p align="center"><img alt="Power Manager sample app view: battery level dropped" src="../images/power_manager_battery_lower.png" border="1"/></p>
+ </td>
+ <td>
+ <p class="figure">Figure 3: Power Manager sample app view: Power Saving mode on.</p>
+ <p align="center"><img alt="Power Manager sample app view: Power Saving mode on" src="../images/power_manager_power_mode_on.png" border="1"/></p>
+ </td>
+</tr>
+<tr>
+ <td>
+ <p class="figure">Figure 4: Power Manager sample app main: turn off settings.</p>
+ <p align="center"><img alt="Power Manager sample app main: turn off settings" src="../images/power_manager_turn_off_settings.png" border="1"/></p>
+ </td>
+ <td>
+ <p class="figure">Figure 5: Power Manager sample app view: turn on settings.</p>
+ <p align="center"><img alt="Power Manager sample app view: turn on settings" src="../images/power_manager_turn_on_settings.png" border="1"/></p>
+ </td>
+ <td>
+ <p class="figure">Figure 6: Power Manager sample app view: device is charging.</p>
+ <p align="center"><img alt="Power Manager sample app view: device is charging" src="../images/power_manager_device_charging.png" border="1"/></p>
+ </td>
+</tr>
+</table>
+
+<p>The main view of the application (as seen in Fig. 1) consists of the following areas (top to bottom):</p>
+ <ul>
+ <li><p><u>Device status area</u></p>
+ <p>Information about device's settings and state is displayed here. There are 5 subareas that convey the following data:</p>
+ <ul>
+ <li>charging status (on/off),</li>
+ <li>Wi-Fi status (on/off),</li>
+ <li>Bluetooth status (on/off),</li>
+ <li>GPS status (on/off),</li>
+ <li>Battery state (percentage and level).</li>
+ </ul>
+ </li>
+ <li><p><u>Battery level warnings area</u></p>
+ <p>This is the control panel for warnings about battery level going too low. The user can set the battery level at which he or she wants to receive warnings using a slider.</p>
+ </li>
+ <li><p><u>Power Saving mode area</u></p>
+ <p>The area consists only of a button the user can use to turn the Power Saving mode on/off.</p>
+ </li>
+ </ul>
+
+
+<h2>Prerequisites</h2>
+<p>To ensure proper application execution, the following privileges must be set:</p>
+ <ul>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/network.get</span> - to read Wi-Fi status;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/network.set</span> - to set Wi-Fi status;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/appmanager.launch</span> - to launch Settings application;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/display</span> - to change display brightness.</li>
+ </ul>
+
+
+<h2>Implementation</h2>
+
+<h3>Acquiring device's information</h3>
+
+<h5>Runtime information + Wi-Fi status</h5>
+
+<p>The Runtime Information API is used in this sample application to obtain the following runtime information:</p>
+<ul>
+ <li>battery charging status (<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_BATTERY_IS_CHARGING</span>),</li>
+ <li>Bluetooth status (<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_BLUETOOTH_ENABLED</span>),</li>
+ <li>GPS status (<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED</span>).</li>
+</ul>
+
+<p>In addition to this information, Wi-Fi status is acquired using the Wi-Fi API. In order to do that,
+the Wi-Fi module needs to be initialized first. It is done using the <span style="font-family: Courier New,Courier,monospace">wifi_initialize()</span>
+function. If the initialization is successful, Wi-Fi status is acquired using <span style="font-family: Courier New,Courier,monospace">wifi_is_activated()</span> function.</p>
+
+<pre class="prettyprint">
+bool dev_manager_get_runtime_info(bool *charging, bool *bluetooth_on, bool *wifi_on, bool *gps_on)
+{
+ if (charging) {
+ *charging = false;
+ if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, charging) != RUNTIME_INFO_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: battery is charging");
+ }
+ }
+ settings_on[SETTINGS_CHARGING] = *charging;
+
+ if (bluetooth_on) {
+ *bluetooth_on = false;
+ if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, bluetooth_on) != RUNTIME_INFO_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: bluetooth enabled");
+ }
+ }
+ settings_on[SETTINGS_BLUETOOTH] = *bluetooth_on;
+
+ if (wifi_on) {
+ *wifi_on = false;
+ if (wifi_initialize() != WIFI_ERROR_NONE || wifi_is_activated(wifi_on) != WIFI_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: wifi enabled");
+ }
+ }
+ settings_on[SETTINGS_WIFI] = *wifi_on;
+
+ if (gps_on) {
+ *gps_on = false;
+ if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, gps_on) != RUNTIME_INFO_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: gps enabled");
+ }
+ }
+ settings_on[SETTINGS_GPS] = *gps_on;
+
+ return true;
+}
+</pre>
+
+<h5>Battery information</h5>
+
+<p>Battery information is obtained using Device/Battery API. The <span style="font-family: Courier New,Courier,monospace">device_battery_get_percent()</span>
+function is used to get the battery level in a form of a percentage whereas the <span style="font-family: Courier New,Courier,monospace">device_battery_get_level_status()</span>
+is used to get the battery level status. The API defines five battery levels:</p>
+<ul>
+ <li>DEVICE_BATTERY_LEVEL_EMPTY (<2%),</li>
+ <li>DEVICE_BATTERY_LEVEL_CRITICAL (2-5%),</li>
+ <li>DEVICE_BATTERY_LEVEL_LOW (6-15%),</li>
+ <li>DEVICE_BATTERY_LEVEL_HIGH (16-95%),</li>
+ <li>DEVICE_BATTERY_LEVEL_FULL (>95%).</li>
+</ul>
+
+<pre class="prettyprint">
+int dev_manager_get_battery_percent(void)
+{
+ int percent = -1;
+
+ if (device_battery_get_percent(&percent) != DEVICE_ERROR_NONE)
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get battery percentage");
+
+ return percent;
+}
+
+char *dev_manager_get_battery_level(void)
+{
+ device_battery_level_e status = DEVICE_BATTERY_LEVEL_EMPTY;
+
+ if (device_battery_get_level_status(&status) != DEVICE_ERROR_NONE)
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get battery level");
+
+ return __format_battery_level_string(status);
+}
+</pre>
+
+<h3>Setting relevant callbacks</h3>
+
+<p>To monitor changes in relevant device's settings and battery state, a set of callbacks is used.</p>
+
+<h5>Runtime information callbacks</h5>
+
+<p>To monitor relevant runtime information, the <span style="font-family: Courier New,Courier,monospace">runtime_info_set_changed()</span> function is used.
+It registers a change event callback for given runtime information key. In case of this application, callbacks are set for
+<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_BLUETOOTH_ENABLED</span>,
+<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED</span> and
+<span style="font-family: Courier New,Courier,monospace">RUNTIME_INFO_KEY_BATTERY_IS_CHARGING</span> keys.</p>
+
+<pre class="prettyprint">
+bool dev_manager_set_runtime_info_callbacks(changed_setting_cb changed_cb)
+{
+ if (runtime_info_set_changed_cb(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE ||
+ runtime_info_set_changed_cb(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE ||
+ runtime_info_set_changed_cb(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set runtime callbacks");
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+<p>When a change event is detected and the <span style="font-family: Courier New,Courier,monospace">__runtime_cb</span> function is invoked which gets
+the runtime information key type as an argument. The new runtime information is used to update the application's UI using
+<span style="font-family: Courier New,Courier,monospace">changed_cb</span> function and the relevant setting's value is stored internally.</p>
+
+<pre class="pretty">
+static void __runtime_cb(runtime_info_key_e key, void *user_data)
+{
+ bool val = false;
+ changed_setting_cb changed_cb;
+
+ if (!user_data) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get cb func");
+ return;
+ }
+
+ changed_cb = (changed_setting_cb)user_data;
+
+ switch (key) {
+ case RUNTIME_INFO_KEY_BLUETOOTH_ENABLED:
+ runtime_info_get_value_bool(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, &val);
+ settings_on[SETTINGS_BLUETOOTH] = val;
+ changed_cb(SETTINGS_BLUETOOTH, settings_on[SETTINGS_BLUETOOTH]);
+ break;
+ case RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED:
+ runtime_info_get_value_bool(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, &val);
+ settings_on[SETTINGS_GPS] = val;
+ changed_cb(SETTINGS_GPS, settings_on[SETTINGS_GPS]);
+ break;
+ case RUNTIME_INFO_KEY_BATTERY_IS_CHARGING:
+ runtime_info_get_value_bool(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, &val);
+ settings_on[SETTINGS_CHARGING] = val;
+ changed_cb(SETTINGS_CHARGING, settings_on[SETTINGS_CHARGING]);
+ break;
+ default:
+ break;
+ }
+}
+</pre>
+
+<h5>Device information callbacks</h5>
+
+<p>In order to be notified about battery state changes, the <span style="font-family: Courier New,Courier,monospace">device_add_callback()</span>
+is invoked for <span style="font-family: Courier New,Courier,monospace">DEVICE_CALLBACK_BATTERY_CAPACITY</span> (battery level percentage) and
+<span style="font-family: Courier New,Courier,monospace">DEVICE_CALLBACK_BATTERY_LEVEL</span> (battery level status) callback types.</p>
+
+<pre class="prettyprint">
+bool dev_manager_set_device_callbacks(changed_bat_percentage_cb percentage_cb, changed_bat_level_cb level_cb)
+{
+ if (device_add_callback(DEVICE_CALLBACK_BATTERY_CAPACITY, __bat_changed_cb, percentage_cb) != DEVICE_ERROR_NONE ||
+ device_add_callback(DEVICE_CALLBACK_BATTERY_LEVEL, __bat_changed_cb, level_cb) != DEVICE_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set device callbacks");
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+<p>The <span style="font-family: Courier New,Courier,monospace">__bat_changed_cb()</span> callback function gets the callback type
+(<span style="font-family: Courier New,Courier,monospace">device_callback_e</span>) as an argument which is then used to update the application's UI accordingly.</p>
+
+<pre class="prettyprint">
+static void __bat_changed_cb(device_callback_e type, void *value, void *user_data)
+{
+ changed_bat_percentage_cb percentage_cb;
+ changed_bat_level_cb level_cb;
+ int val = (int)value;
+
+ if (!user_data) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get cb func");
+ return;
+ }
+
+ switch (type) {
+ case DEVICE_CALLBACK_BATTERY_CAPACITY:
+ percentage_cb = (changed_bat_percentage_cb)user_data;
+ percentage_cb(val);
+ break;
+ case DEVICE_CALLBACK_BATTERY_LEVEL:
+ level_cb = (changed_bat_level_cb)user_data;
+ level_cb(__format_battery_level_string((device_battery_level_e)val));
+ break;
+ default:
+ break;
+ }
+}
+</pre>
+
+<h3>Setting display brightness</h3>
+
+<p>When the Power Saving mode is enabled, the application changes the device's display brightness. The Device/Display API is used to do that.
+The code snippet below shows the implementation of this feature.</p>
+
+<pre class="prettyprint">
+bool dev_manager_power_mode_set_brightness(Eina_Bool to_low)
+{
+ int max = 0;
+ int percent = to_low ? BRIGHTNESS_LEVEL_LOW : BRIGHTNESS_LEVEL_FULL;
+
+ if (device_display_get_max_brightness(0, &max) != DEVICE_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get max brightness");
+ return false;
+ }
+
+ if (device_display_set_brightness(0, (int)percent*max/100) != DEVICE_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set brightness");
+ return false;
+ }
+
+ return true;
+}
+</pre>
+
+<h3>Turning Settings on/off</h3>
+
+<p>To reduce power consumption when in Power Saving mode, the sample application allows the user to turn more power consuming
+settings off. Wi-Fi deactivation is done automatically using <span style="font-family: Courier New,Courier,monospace">wifi_deactivate()</span> function.</p>
+
+<pre class="prettyprint">
+bool dev_manager_power_mode_settings_off(Eina_Bool turn_off)
+{
+ if (turn_off) {
+ if (settings_on[SETTINGS_WIFI] && wifi_deactivate(NULL, NULL) != WIFI_ERROR_NONE)
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to deactivate Wi-Fi");
+
+ if (settings_on[SETTINGS_GPS])
+ __launch_setting_location_app();
+
+ if (settings_on[SETTINGS_BLUETOOTH])
+ __launch_bluetooth_app();
+ } else {
+ if (settings_on[SETTINGS_WIFI] && wifi_activate(NULL, NULL) != WIFI_ERROR_NONE)
+ dlog_print(DLOG_INFO, LOG_TAG, "Failed to activate Wi-Fi");
+
+ if (!settings_on[SETTINGS_GPS])
+ __launch_setting_location_app();
+
+ if (!settings_on[SETTINGS_BLUETOOTH])
+ __launch_bluetooth_app();
+ }
+
+ return true;
+}
+</pre>
+
+<h5>Launching Settings application</h5>
+
+<p>Changing the state of GPS or Bluetooth is not allowed for regular applications. To allow the user to conveniently change these settings, the Power Manager sample applications
+launches relevant module of Settings application upon user's request. App Control API is used to do that.
+In case of Bluetooth, <span style="font-family: Courier New,Courier,monospace">application/x-bluetooth-on-off</span> is set explicitly as the MIME type of the data to be edited, whereas
+in case of GPS settings, <span style="font-family: Courier New,Courier,monospace">org.tizen.setting-location</span> app ID is set, also with 'edit' operation type.
+See the code snippets below for the Settings application launching implementation.</p>
+
+<pre class="prettyprint">
+static void __launch_bluetooth_app(void)
+{
+ app_control_h service = NULL;
+
+ app_control_create(&service);
+ if (!service) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create app control handle");
+ return;
+ }
+
+ app_control_set_operation(service, "http://tizen.org/appcontrol/operation/edit");
+ app_control_set_mime(service, "application/x-bluetooth-on-off");
+
+ if (app_control_send_launch_request(service, NULL, NULL) != APP_CONTROL_ERROR_NONE)
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to launch Bluetooth On/Off app");
+
+ app_control_destroy(service);
+}
+</pre>
+
+<pre class="prettyprint">
+static void __launch_setting_location_app(void)
+{
+ app_control_h service = NULL;
+
+ app_control_create(&service);
+ if (!service) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create app control handle");
+ return;
+ }
+
+ app_control_set_operation(service, "http://tizen.org/appcontrol/operation/edit");
+ app_control_set_app_id(service, "org.tizen.setting-location");
+
+ if (app_control_send_launch_request(service, NULL, NULL) != APP_CONTROL_ERROR_NONE)
+ dlog_print(DLOG_ERROR, LOG_TAG, "Failed to launch Location Settings app");
+
+ app_control_destroy(service);
+}
+</pre>
+
+
+<script type="text/javascript" src="../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-25976949-1']);
+_gaq.push(['_trackPageview']);
+(function() {
+var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();
+</script>
+
+</body>
+</html>
\ No newline at end of file
projects / sdk / online-doc.git / commitdiff
