From: Szymon Jastrzebski Date: Tue, 8 Aug 2017 12:16:28 +0000 (+0200) Subject: [Application] Updating Wearable API Reference X-Git-Tag: GitHub/PR#40/tizen-studio~67^2~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8fdd5ebc43de345b0d8fcf6e27c61cbea1e14a5c;p=sdk%2Fonline-doc.git [Application] Updating Wearable API Reference The change was needed because of transforming getBatteryUsage() into async method. Change-Id: Ice07d99c49417425c246e124191380623ff96f42 Signed-off-by: Szymon Jastrzebski --- 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 --- 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 ApplicationMetaData -
  • 2.12. ApplicationInformationArraySuccessCallback +
  • 2.12. BatteryUsageInfoArraySuccessCallback
    • -
  • 2.13. FindAppControlSuccessCallback +
  • 2.13. ApplicationInformationArraySuccessCallback
    • -
  • 2.14. ApplicationContextArraySuccessCallback +
  • 2.14. FindAppControlSuccessCallback
    • -
  • 2.15. ApplicationControlDataArrayReplyCallback +
  • 2.15. ApplicationContextArraySuccessCallback
    • -
  • 2.16. SystemEventData +
  • 2.16. ApplicationControlDataArrayReplyCallback
    • -
  • 2.17. EventCallback +
  • 2.17. SystemEventData
    • -
  • 2.18. StatusEventCallback +
  • 2.18. EventCallback
    • -
  • 2.19. EventInfo +
  • 2.19. StatusEventCallback +
    • +
  • 2.20. EventInfo
    • -
  • 3. Full WebIDL +
  • 3. Related Feature +
    • +
  • 4. Full WebIDL
    • @@ -135,8 +139,7 @@ For more information on the Application features, see getAppSharedURI (optional ApplicationId? id)
    ApplicationMetaData[] getAppMetaData (optional ApplicationId? id)
    -
    -ApplicationBatteryUsage[] getBatteryUsageInfo (optional long? days, optional long? limit)
    +
    void getBatteryUsageInfo (BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? days, optional long? limit)
    long addAppStatusChangeListener (StatusEventCallback eventCallback, optional ApplicationId? appId)
    void removeAppStatusChangeListener (long watchId)
    @@ -190,6 +193,10 @@ For more information on the Application features, see BatteryUsageInfoArraySuccessCallback +
    void onsuccess (ApplicationBatteryUsage[] batteryInfoArray)
    + + ApplicationInformationArraySuccessCallback
    void onsuccess (ApplicationInformation[] informationArray)
    @@ -359,7 +366,10 @@ The tizen.application object allows access to the Application API's fun ApplicationMetaData[] getAppMetaData(optional ApplicationId? id) raises(WebAPIException); - ApplicationBatteryUsage[] getBatteryUsageInfo(optional long? days, optional long? limit) raises(WebAPIException); + void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback, + optional ErrorCallback? errorCallback, + optional long? days, + optional long? limit) raises(WebAPIException); long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException); @@ -1192,9 +1202,9 @@ console.log("size of metadata: " + metaDataArray.length);
    - Returns information about battery usage per application. + Gets information about battery usage per application.
    -
    ApplicationBatteryUsage[] getBatteryUsageInfo(optional long? days, optional long? limit);
+
    void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? days, optional long? limit);
              
    
 
    
             Since: 
@@ -1202,14 +1212,21 @@ console.log("size of metadata: " + metaDataArray.length);
             
    
 
    
             
    
-This method returns information about battery usage collected in last days days.
+This method provides information about battery usage collected in last days days, through callback successCallback.
+Maximum number of retrieved objects can be set in limit parameter.
             
    
             
    
-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 days is not given, this method retrieves information about battery usage since the time the device was unplugged, after reaching full charge.
             
    
             
    
-You can also determine number of returned objects.
+The ErrorCallback method is launched with these error types:
             
    
+            
      
+              
    • 
+AbortError - if any system error occurred.              
      • 
+              
    • 
+InvalidValuesError - if any of the input parameters contains an invalid value.              
      • 
+            
    
            
    
 
    
             Privilege level: 
@@ -1226,19 +1243,24 @@ You can also determine number of returned objects.
 
    Parameters:
    
 
      
           
    • 
+successCallback:
+ The method to call when the invocation ends successfully.
+                
      • 
+          
    • 
+errorCallback [optional] [nullable]:
+ The method to call when an error occurs.
+                
      • 
+          
    • 
 days [optional] [nullable]:
- 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.
                 
      • 
           
    • 
 limit [optional] [nullable]:
- This parameter defines maximum count of objects ApplicationBatteryUsage in returned array. If parameter wasn't given, it is set to 30.
+ This parameter defines maximum number of ApplicationBatteryUsage objects in an array in successCallback callback.
+By default, it is set to 30.
                 
      •
    -
    -

    Return value:

    - ApplicationBatteryUsage[] Array of data containing information about battery usage per application. -

    Exceptions:

    • WebAPIException
        @@ -1246,32 +1268,31 @@ You can also determine number of returned objects. with error type NotSupportedError, if this feature is not supported.

      • - with error type InvalidValuesError, if any of the input parameters contain an invalid value. -

        • -

      • with error type SecurityError, if the application does not have the privilege to call this method.

      • - 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.

    -

    Code example:

    -var batteryUsageInfoArray = tizen.application.getBatteryUsageInfo();
-batteryUsageInfoArray.forEach(function(abuinfo) {
-  console.log("ApplicationID: " + abuinfo.appId + ", usage: " + abuinfo.batteryUsage);
-});
-
    +

    Code example:

     var successCallback = function(batteryUsageInfoArray)
+ {
+   batteryUsageInfoArray.forEach(function(abuInfo)
+   {
+     console.log("ApplicationID: " + abuInfo.appId + ", usage: " + abuInfo.batteryUsage);
+   });
+ };
+
+ tizen.application.getBatteryUsageInfo(successCallback);
+

    Output example:

     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.
 
  • 
                 readonly
 ApplicationId appId
    
- An attribute storing ID of an installed application.
+ An attribute storing ID of an application.
             
    
 
    
             Since: 
@@ -2041,7 +2062,9 @@ application.
 
  • 
                 readonly
 double batteryUsage
    
- An attribute which stores information about battery usage of an application with ApplicationId appId, 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 appId.
+Battery usage is a ratio of battery consumption of the application with ApplicationId appId to the total battery consumption of all applications.
+The attribute value scales from 0 to 1, the higher value, the more battery is consumed.
             
    
 
    
             Since: 
@@ -2439,8 +2462,58 @@ if (reqAppControl)
    • +
    +

    2.12. BatteryUsageInfoArraySuccessCallback

    +
    + This callback interface specifies a success callback that is invoked when the battery usage per application array is retrieved. +
    +
      [Callback=FunctionOnly, NoInterfaceObject] interface BatteryUsageInfoArraySuccessCallback {
+    void onsuccess(ApplicationBatteryUsage[] batteryInfoArray);
+  };
    +

    + Since: + 4.0 +

    +
    +

    +This callback interface specifies a success method with an array of +ApplicationBatteryUsage objects as an input parameter. It is used in ApplicationManager.getBatteryUsageInfo() method. +

    +
    +
    +

    Methods

    +
    +
    +onsuccess +
    +
    +
    + Called when the asynchronous call completes successfully. +
    +
    void onsuccess(ApplicationBatteryUsage[] batteryInfoArray);
+
    +

    + Since: + 4.0 +

    +

    Remark : + Example of usage can be find at getBatteryUsageInfo code example. +

    +
    +

    Parameters:

    +
      +
    • +batteryInfoArray: + An array of data containing information about battery usage per application. +
      • +
    +
    +
    +
    +
    +
    -

    2.12. ApplicationInformationArraySuccessCallback

    +

    2.13. ApplicationInformationArraySuccessCallback

    This callback interface specifies a success callback that is invoked when the installed application list is retrieved.
    @@ -2498,7 +2571,7 @@ tizen.application.getAppsInfo(onListInstalledApps);
    -

    2.13. FindAppControlSuccessCallback

    +

    2.14. FindAppControlSuccessCallback

    This callback interface specifies a success callback that is invoked when the system has finished searching applications that match a specific application control .
    @@ -2587,7 +2660,7 @@ tizen.application.findAppControl(appControl, successCB);
    -

    2.14. ApplicationContextArraySuccessCallback

    +

    2.15. ApplicationContextArraySuccessCallback

    This callback interface specifies a success callback that is invoked when the list of running applications is retrieved.
    @@ -2634,7 +2707,7 @@ an array of ApplicationContext objects as an input parameter. It is use
    -

    2.15. ApplicationControlDataArrayReplyCallback

    +

    2.16. ApplicationControlDataArrayReplyCallback

    The ApplicationControlDataArrayReplyCallback callback specifies success callbacks that are invoked as a reply from the requested application control within the application control requester.
    @@ -2732,7 +2805,7 @@ tizen.application.launchAppControl(appControl, null,
    -

    2.16. SystemEventData

    +

    2.17. SystemEventData

    The SystemEventData interface defines what is retrieved from the event listener.
    @@ -2751,7 +2824,7 @@ Platform modules will be able to broadcast system events in a future Tizen relea
    -

    2.17. EventCallback

    +

    2.18. EventCallback

    The EventCallback interface specifies a callback for getting notified when a specified event occurs.
    @@ -2829,7 +2902,7 @@ tizen.application.getAppsInfo(onListInstalledApps);
    -

    2.18. StatusEventCallback

    +

    2.19. StatusEventCallback

    The StatusEventCallback interface specifies a callback for getting notified when status of the installed application has been changed.
    @@ -2879,7 +2952,7 @@ Example of using can be find at -

    2.19. EventInfo

    +

    2.20. EventInfo

    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.
    @@ -2938,7 +3011,21 @@ Must be at least 1 byte in length and not exceed the maximum name length of 127
    -

    3. Full WebIDL

    +

    3. Related Feature

    +
    + You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API. +
    +

    +

    +To guarantee the running of the application on a device which has battery, declare the following feature requirement in the config file: +

    +

    +
  • http://tizen.org/feature/battery
    • +
    +

    + For more information, see Application Filtering. +
    +

    4. Full WebIDL

    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
 
     ApplicationMetaData[] getAppMetaData(optional ApplicationId? id) raises(WebAPIException);
 
-    ApplicationBatteryUsage[] getBatteryUsageInfo(optional long? days, optional long? limit) raises(WebAPIException);
+    void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback,
+                             optional ErrorCallback? errorCallback,
+                             optional long? days,
+                             optional long? limit) raises(WebAPIException);
 
     long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException);
 
@@ -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(ApplicationBatteryUsage[] batteryInfoArray);
+  };
+
   [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationInformationArraySuccessCallback {
     void onsuccess(ApplicationInformation[] informationArray);
   };