[Application] Updating Wearable API Reference

The change was needed because of transforming getBatteryUsage() into
async method.

Change-Id: Ice07d99c49417425c246e124191380623ff96f42
Signed-off-by: Szymon Jastrzebski <s.jastrzebsk@partner.samsung.com>

diff --git a/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html b/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html
index 924441a..0d44d52 100755 (executable)
--- a/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html
+++ b/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html
@@ -82,25 +82,29 @@ For more information on the Application features, see <a href="https://developer
 </li>
 <li>2.11. <a href="#ApplicationMetaData">ApplicationMetaData</a>
 </li>
-<li>2.12. <a href="#ApplicationInformationArraySuccessCallback">ApplicationInformationArraySuccessCallback</a>
+<li>2.12. <a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a>
 </li>
-<li>2.13. <a href="#FindAppControlSuccessCallback">FindAppControlSuccessCallback</a>
+<li>2.13. <a href="#ApplicationInformationArraySuccessCallback">ApplicationInformationArraySuccessCallback</a>
 </li>
-<li>2.14. <a href="#ApplicationContextArraySuccessCallback">ApplicationContextArraySuccessCallback</a>
+<li>2.14. <a href="#FindAppControlSuccessCallback">FindAppControlSuccessCallback</a>
 </li>
-<li>2.15. <a href="#ApplicationControlDataArrayReplyCallback">ApplicationControlDataArrayReplyCallback</a>
+<li>2.15. <a href="#ApplicationContextArraySuccessCallback">ApplicationContextArraySuccessCallback</a>
 </li>
-<li>2.16. <a href="#SystemEventData">SystemEventData</a>
+<li>2.16. <a href="#ApplicationControlDataArrayReplyCallback">ApplicationControlDataArrayReplyCallback</a>
 </li>
-<li>2.17. <a href="#EventCallback">EventCallback</a>
+<li>2.17. <a href="#SystemEventData">SystemEventData</a>
 </li>
-<li>2.18. <a href="#StatusEventCallback">StatusEventCallback</a>
+<li>2.18. <a href="#EventCallback">EventCallback</a>
 </li>
-<li>2.19. <a href="#EventInfo">EventInfo</a>
+<li>2.19. <a href="#StatusEventCallback">StatusEventCallback</a>
+</li>
+<li>2.20. <a href="#EventInfo">EventInfo</a>
 </li>
 </ul>
 </li>
-<li>3. <a href="#full-webidl">Full WebIDL</a>
+<li>3. <a href="#api-features">Related Feature</a>
+</li>
+<li>4. <a href="#full-webidl">Full WebIDL</a>
 </li>
 </ul>
 <hr>
@@ -135,8 +139,7 @@ For more information on the Application features, see <a href="https://developer
 <div>DOMString <a href="#ApplicationManager::getAppSharedURI">getAppSharedURI</a> (optional <a href="#ApplicationId">ApplicationId</a>? id)</div>
 <div>
 <a href="#ApplicationMetaData">ApplicationMetaData</a>[] <a href="#ApplicationManager::getAppMetaData">getAppMetaData</a> (optional <a href="#ApplicationId">ApplicationId</a>? id)</div>
-<div>
-<a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] <a href="#ApplicationManager::getBatteryUsageInfo">getBatteryUsageInfo</a> (optional long? days, optional long? limit)</div>
+<div>void <a href="#ApplicationManager::getBatteryUsageInfo">getBatteryUsageInfo</a> (<a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a> successCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback, optional long? days, optional long? limit)</div>
 <div>long <a href="#ApplicationManager::addAppStatusChangeListener">addAppStatusChangeListener</a> (<a href="#StatusEventCallback">StatusEventCallback</a> eventCallback, optional <a href="#ApplicationId">ApplicationId</a>? appId)</div>
 <div>void <a href="#ApplicationManager::removeAppStatusChangeListener">removeAppStatusChangeListener</a> (long watchId)</div>
 </td>
@@ -190,6 +193,10 @@ For more information on the Application features, see <a href="https://developer
 <td></td>
 </tr>
 <tr>
+<td><a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a></td>
+<td><div>void <a href="#BatteryUsageInfoArraySuccessCallback::onsuccess">onsuccess</a> (<a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] batteryInfoArray)</div></td>
+</tr>
+<tr>
 <td><a href="#ApplicationInformationArraySuccessCallback">ApplicationInformationArraySuccessCallback</a></td>
 <td><div>void <a href="#ApplicationInformationArraySuccessCallback::onsuccess">onsuccess</a> (<a href="#ApplicationInformation">ApplicationInformation</a>[] informationArray)</div></td>
 </tr>
@@ -359,7 +366,10 @@ The <em>tizen.application </em>object allows access to the Application API's fun
 
     <a href="#ApplicationMetaData">ApplicationMetaData</a>[] getAppMetaData(optional <a href="#ApplicationId">ApplicationId</a>? id) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
-    <a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] getBatteryUsageInfo(optional long? days, optional long? limit) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+    void getBatteryUsageInfo(<a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a> successCallback,
+                             optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback,
+                             optional long? days,
+                             optional long? limit) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
     long addAppStatusChangeListener(<a href="#StatusEventCallback">StatusEventCallback</a> eventCallback, optional <a href="#ApplicationId">ApplicationId</a>? appId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
@@ -1192,9 +1202,9 @@ console.log("size of metadata: " + metaDataArray.length);
 </dt>
 <dd>
 <div class="brief">
- Returns information about battery usage per application.
+ Gets information about battery usage per application.
             </div>
-<div class="synopsis"><pre class="signature prettyprint"><a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] getBatteryUsageInfo(optional long? days, optional long? limit);
+<div class="synopsis"><pre class="signature prettyprint">void getBatteryUsageInfo(<a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a> successCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback, optional long? days, optional long? limit);
              </pre></div>
 <p><span class="version">
             Since: </span>
@@ -1202,14 +1212,21 @@ console.log("size of metadata: " + metaDataArray.length);
             </p>
 <div class="description">
             <p>
-This method returns information about battery usage collected in last <var>days</var> days.
+This method provides information about battery usage collected in last <var>days</var> days, through callback <em>successCallback</em>.
+Maximum number of retrieved objects can be set in <em>limit</em> parameter.
             </p>
             <p>
-If the first parameter wasn't given, this method will return information about battery usage since last charge. Last charge means the time when device was unplugged, after reaching full charge.
+If the <em>days</em> is not given, this method retrieves information about battery usage since the time the device was unplugged, after reaching full charge.
             </p>
             <p>
-You can also determine number of returned objects.
+The <em>ErrorCallback</em> method is launched with these error types:
             </p>
+            <ul>
+              <li>
+AbortError - if any system error occurred.              </li>
+              <li>
+InvalidValuesError - if any of the input parameters contains an invalid value.              </li>
+            </ul>
            </div>
 <p><span class="privilegelevel">
             Privilege level: </span>
@@ -1226,19 +1243,24 @@ You can also determine number of returned objects.
 <p><span class="param">Parameters:</span></p>
 <ul>
           <li class="param">
+<span class="name">successCallback</span>:
+ The method to call when the invocation ends successfully.
+                </li>
+          <li class="param">
+<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
+ The method to call when an error occurs.
+                </li>
+          <li class="param">
 <span class="name">days</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
- Number of days. If parameter wasn't given, method will behave as described above.
+ Number of days. If parameter was not given, method will behave as described above.
                 </li>
           <li class="param">
 <span class="name">limit</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
- This parameter defines maximum count of objects <em>ApplicationBatteryUsage</em> in returned array. If parameter wasn't given, it is set to <var>30</var>.
+ This parameter defines maximum number of <em>ApplicationBatteryUsage</em> objects in an array in <em>successCallback</em> callback.
+By default, it is set to <var>30</var>.
                 </li>
         </ul>
 </div>
-<div class="returntype">
-<p><span class="return">Return value:</span></p>
- ApplicationBatteryUsage[] Array of data containing information about battery usage per application.
-              </div>
 <div class="exceptionlist">
 <p><span class="except">Exceptions:</span></p>
           <ul class="exception"><li>WebAPIException<ul>
@@ -1246,32 +1268,31 @@ You can also determine number of returned objects.
  with error type NotSupportedError, if this feature is not supported.
                 </p></li>
 <li class="list"><p>
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
-                </p></li>
-<li class="list"><p>
  with error type SecurityError, if the application does not have the privilege to call this method.
                 </p></li>
 <li class="list"><p>
- with error type AbortError, if any system error occurred.
+ with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
                 </p></li>
 </ul>
 </li></ul>
         </div>
 <div class="example">
-<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
-var batteryUsageInfoArray = tizen.application.getBatteryUsageInfo();
-batteryUsageInfoArray.forEach(function(abuinfo) {
-&nbsp;&nbsp;console.log("ApplicationID: " + abuinfo.appId + ", usage: " + abuinfo.batteryUsage);
-});
-</pre>
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> var successCallback = function(batteryUsageInfoArray)
+ {
+   batteryUsageInfoArray.forEach(function(abuInfo)
+   {
+     console.log("ApplicationID: " + abuInfo.appId + ", usage: " + abuInfo.batteryUsage);
+   });
+ };
+
+ tizen.application.getBatteryUsageInfo(successCallback);
+ </pre>
 </div>
 <div class="output">
 <span class="title"><p>Output example:</p></span><pre> ApplicationID: 3gWRkEPXz5.BasicUI3, usage: 51.78
- ApplicationID: org.tizen.homescreen-efl, usage: 19.98
+ ApplicationID: org.tizen.homescreen-efl, usage: 28.72
  ApplicationID: org.tizen.lockscreen, usage: 6.05
  ApplicationID: org.tizen.quickpanel, usage: 4.83
- ApplicationID: org.tizen.crash-syspopup, usage: 4.46
- ApplicationID: ise-default, usage: 4.28
  ApplicationID: org.tizen.indicator, usage: 3.69
  ApplicationID: org.tizen.calendar.widget, usage: 1.79
  ApplicationID: org.tizen.volume, usage: 1.34
@@ -2031,7 +2052,7 @@ application.
 <li class="attribute" id="ApplicationBatteryUsage::appId">
 <span class="attrName"><span class="readonly">                readonly
 </span><span class="type">ApplicationId </span><span class="name">appId</span></span><div class="brief">
- An attribute storing ID of an installed application.
+ An attribute storing ID of an application.
             </div>
 <p><span class="version">
             Since: </span>
@@ -2041,7 +2062,9 @@ application.
 <li class="attribute" id="ApplicationBatteryUsage::batteryUsage">
 <span class="attrName"><span class="readonly">                readonly
 </span><span class="type">double </span><span class="name">batteryUsage</span></span><div class="brief">
- An attribute which stores information about battery usage of an application with ApplicationId <em>appId</em>, in percentage. Battery usage is calculated based on CPU usage per application.
+ An attribute which stores information about battery usage of an application with ApplicationId <em>appId</em>.
+Battery usage is a ratio of battery consumption of the application with ApplicationId <em>appId</em> to the total battery consumption of all applications.
+The attribute value scales from <var>0</var> to <var>1</var>, the higher value, the more battery is consumed.
             </div>
 <p><span class="version">
             Since: </span>
@@ -2439,8 +2462,58 @@ if (reqAppControl)
 </ul>
 </div>
 </div>
+<div class="interface" id="BatteryUsageInfoArraySuccessCallback">
+<a class="backward-compatibility-anchor" name="::Application::BatteryUsageInfoArraySuccessCallback"></a><h3>2.12. BatteryUsageInfoArraySuccessCallback</h3>
+<div class="brief">
+ This callback interface specifies a success callback that is invoked when the battery usage per application array is retrieved.
+          </div>
+<pre class="webidl prettyprint">  [Callback=FunctionOnly, NoInterfaceObject] interface BatteryUsageInfoArraySuccessCallback {
+    void onsuccess(<a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] batteryInfoArray);
+  };</pre>
+<p><span class="version">
+            Since: </span>
+ 4.0
+          </p>
+<div class="description">
+          <p>
+This callback interface specifies a success method with an array of
+<em>ApplicationBatteryUsage</em> objects as an input parameter. It is used in <em>ApplicationManager.getBatteryUsageInfo()</em> method.
+          </p>
+         </div>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="BatteryUsageInfoArraySuccessCallback::onsuccess">
+<a class="backward-compatibility-anchor" name="::Application::BatteryUsageInfoArraySuccessCallback::onsuccess"></a><code><b><span class="methodName">onsuccess</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Called when the asynchronous call completes successfully.
+            </div>
+<div class="synopsis"><pre class="signature prettyprint">void onsuccess(<a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] batteryInfoArray);
+             </pre></div>
+<p><span class="version">
+            Since: </span>
+ 4.0
+            </p>
+<p><span class="remark"> Remark : </span>
+ Example of usage can be find at <a href="#ApplicationManager::getBatteryUsageInfo">getBatteryUsageInfo</a> code example.
+            </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+          <li class="param">
+<span class="name">batteryInfoArray</span>:
+ An array of data containing information about battery usage per application.
+                </li>
+        </ul>
+</div>
+</dd>
+</dl>
+</div>
+</div>
 <div class="interface" id="ApplicationInformationArraySuccessCallback">
-<a class="backward-compatibility-anchor" name="::Application::ApplicationInformationArraySuccessCallback"></a><h3>2.12. ApplicationInformationArraySuccessCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::ApplicationInformationArraySuccessCallback"></a><h3>2.13. ApplicationInformationArraySuccessCallback</h3>
 <div class="brief">
  This callback interface specifies a success callback that is invoked when the installed application list is retrieved.
           </div>
@@ -2498,7 +2571,7 @@ tizen.application.getAppsInfo(onListInstalledApps);
 </div>
 </div>
 <div class="interface" id="FindAppControlSuccessCallback">
-<a class="backward-compatibility-anchor" name="::Application::FindAppControlSuccessCallback"></a><h3>2.13. FindAppControlSuccessCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::FindAppControlSuccessCallback"></a><h3>2.14. FindAppControlSuccessCallback</h3>
 <div class="brief">
  This callback interface specifies a success callback that is invoked when the system has finished searching applications that match a specific application control .
           </div>
@@ -2587,7 +2660,7 @@ tizen.application.findAppControl(appControl, successCB);
 </div>
 </div>
 <div class="interface" id="ApplicationContextArraySuccessCallback">
-<a class="backward-compatibility-anchor" name="::Application::ApplicationContextArraySuccessCallback"></a><h3>2.14. ApplicationContextArraySuccessCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::ApplicationContextArraySuccessCallback"></a><h3>2.15. ApplicationContextArraySuccessCallback</h3>
 <div class="brief">
  This callback interface specifies a success callback that is invoked when the list of running applications is retrieved.
           </div>
@@ -2634,7 +2707,7 @@ an array of <em>ApplicationContext </em>objects as an input parameter. It is use
 </div>
 </div>
 <div class="interface" id="ApplicationControlDataArrayReplyCallback">
-<a class="backward-compatibility-anchor" name="::Application::ApplicationControlDataArrayReplyCallback"></a><h3>2.15. ApplicationControlDataArrayReplyCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::ApplicationControlDataArrayReplyCallback"></a><h3>2.16. ApplicationControlDataArrayReplyCallback</h3>
 <div class="brief">
  The ApplicationControlDataArrayReplyCallback callback specifies success callbacks that are invoked as a reply from the requested application control within the application control requester.
           </div>
@@ -2732,7 +2805,7 @@ tizen.application.launchAppControl(appControl, null,
 </div>
 </div>
 <div class="interface" id="SystemEventData">
-<a class="backward-compatibility-anchor" name="::Application::SystemEventData"></a><h3>2.16. SystemEventData</h3>
+<a class="backward-compatibility-anchor" name="::Application::SystemEventData"></a><h3>2.17. SystemEventData</h3>
 <div class="brief">
  The SystemEventData interface defines what is retrieved from the event listener.
           </div>
@@ -2751,7 +2824,7 @@ Platform modules will be able to broadcast system events in a future Tizen relea
          </div>
 </div>
 <div class="interface" id="EventCallback">
-<a class="backward-compatibility-anchor" name="::Application::EventCallback"></a><h3>2.17. EventCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::EventCallback"></a><h3>2.18. EventCallback</h3>
 <div class="brief">
  The EventCallback interface specifies a callback for getting notified when a specified event occurs.
           </div>
@@ -2829,7 +2902,7 @@ tizen.application.getAppsInfo(onListInstalledApps);
 </div>
 </div>
 <div class="interface" id="StatusEventCallback">
-<a class="backward-compatibility-anchor" name="::Application::StatusEventCallback"></a><h3>2.18. StatusEventCallback</h3>
+<a class="backward-compatibility-anchor" name="::Application::StatusEventCallback"></a><h3>2.19. StatusEventCallback</h3>
 <div class="brief">
  The StatusEventCallback interface specifies a callback for getting notified when status of the installed application has been changed.
           </div>
@@ -2879,7 +2952,7 @@ Example of using can be find at <a href="application.html#ApplicationManager::ad
 </div>
 </div>
 <div class="dictionary" id="EventInfo">
-<a class="backward-compatibility-anchor" name="::Application::EventInfo"></a><h3>2.19. EventInfo</h3>
+<a class="backward-compatibility-anchor" name="::Application::EventInfo"></a><h3>2.20. EventInfo</h3>
 <div class="brief">
  The EventInfo dictionary identifies an event with information such as event name. If it is an user event, the broadasting application's identifier is also specified.
           </div>
@@ -2938,7 +3011,21 @@ Must be at least 1 byte in length and not exceed the maximum name length of 127
 </div>
 </div>
 </div>
-<h2 id="full-webidl">3. Full WebIDL</h2>
+<h2 id="api-features">3. Related Feature</h2>
+<div id="def-api-features" class="def-api-features">
+        You can check if this API is supported with <em>tizen.systeminfo.getCapability()</em> and decide enable/disable codes that need this API.
+                    <div class="def-api-feature">
+<p><div class="description">
+            <p>
+To guarantee the running of the application on a device which has battery, declare the following feature requirement in the config file:
+            </p>
+           </div></p>
+<li class="feature">http://tizen.org/feature/battery</li>
+</div>
+<p></p>
+                    For more information, see <a href="https://developer.tizen.org/development/getting-started/web-application/understanding-tizen-programming/application-filtering">Application Filtering.</a>
+</div>
+<h2 id="full-webidl">4. Full WebIDL</h2>
 <pre class="webidl prettyprint">module Application {
 
   typedef DOMString ApplicationId;
@@ -2994,7 +3081,10 @@ Must be at least 1 byte in length and not exceed the maximum name length of 127
 
     <a href="#ApplicationMetaData">ApplicationMetaData</a>[] getAppMetaData(optional <a href="#ApplicationId">ApplicationId</a>? id) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
-    <a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] getBatteryUsageInfo(optional long? days, optional long? limit) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+    void getBatteryUsageInfo(<a href="#BatteryUsageInfoArraySuccessCallback">BatteryUsageInfoArraySuccessCallback</a> successCallback,
+                             optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback,
+                             optional long? days,
+                             optional long? limit) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
     long addAppStatusChangeListener(<a href="#StatusEventCallback">StatusEventCallback</a> eventCallback, optional <a href="#ApplicationId">ApplicationId</a>? appId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
 
@@ -3109,6 +3199,10 @@ Must be at least 1 byte in length and not exceed the maximum name length of 127
   };
 
 
+  [Callback=FunctionOnly, NoInterfaceObject] interface BatteryUsageInfoArraySuccessCallback {
+    void onsuccess(<a href="#ApplicationBatteryUsage">ApplicationBatteryUsage</a>[] batteryInfoArray);
+  };
+
   [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationInformationArraySuccessCallback {
     void onsuccess(<a href="#ApplicationInformation">ApplicationInformation</a>[] informationArray);
   };