From: Szymon Jastrzebski Date: Thu, 10 Aug 2017 09:49:52 +0000 (+0200) Subject: [Application] Adding getAppsUsageInfo method Wearable API Reference X-Git-Tag: GitHub/PR#40/tizen-studio~67^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F52%2F143552%2F2;p=sdk%2Fonline-doc.git [Application] Adding getAppsUsageInfo method Wearable API Reference Change-Id: I248682907203b3b7e893789f8488f040c4a1c306 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 0d44d52..fb957c6 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 @@ -57,6 +57,9 @@ For more information on the Application features, see ApplicationControlLaunchMode +
  • + 1.6. ApplicationUsageMode +
  • 2. Interfaces
    • @@ -140,11 +149,16 @@ For more information on the Application features, see ApplicationMetaData[] getAppMetaData (optional ApplicationId? id)
    void getBatteryUsageInfo (BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? days, optional long? limit)
    +
    void getAppsUsageInfo (AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit)
    long addAppStatusChangeListener (StatusEventCallback eventCallback, optional ApplicationId? appId)
    void removeAppStatusChangeListener (long watchId)
    +ApplicationUsageFilter + + + Application
    void exit ()
    @@ -170,6 +184,10 @@ For more information on the Application features, see ApplicationUsage + + + ApplicationControlData @@ -197,6 +215,10 @@ For more information on the Application features, see onsuccess (ApplicationBatteryUsage[] batteryInfoArray) +AppsUsageInfoArraySuccessCallback +
    void onsuccess (ApplicationUsage[] appsInfoArray)
    + + ApplicationInformationArraySuccessCallback
    void onsuccess (ApplicationInformation[] informationArray)
    @@ -301,6 +323,28 @@ GROUP - Launch application in subgroup +
    +

    1.6. ApplicationUsageMode

    +
    + Specifies the possible modes of getting statistics of application usage. +
    +
      enum ApplicationUsageMode { "RECENTLY", "FREQUENTLY" };
    +

    + Since: + 4.0 +

    +
    +

    +Possible types are: +

    +
      +
    • +RECENTLY - indicates most recently used applications, in a descending order of the application use counts
      • +
    • +FREQUENTLY - indicates most frequently used applications, in a descending order of the application use counts
      • +
    +
    +

    2. Interfaces

    @@ -371,6 +415,12 @@ The tizen.application object allows access to the Application API's fun optional long? days, optional long? limit) raises(WebAPIException); + void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, + optional ErrorCallback? errorCallback, + optional ApplicationUsageMode? mode, + optional ApplicationUsageFilter? filter, + optional long? limit) raises(WebAPIException); + long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException); void removeAppStatusChangeListener(long watchId) raises(WebAPIException); @@ -1302,6 +1352,117 @@ By default, it is set to 30.
    +
    +getAppsUsageInfo +
    +
    +
    + Gets the usage statistics of applications. +
    +
    void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit);
+
    +

    + Since: + 4.0 +

    +
    +

    +The method gets the most frequently or recently used applications statistics, depending on parameter mode, +which meet conditions in filter object. +Maximum number of retrieved objects can be set in limit parameter. +

    +

    +Applications which have not been used will not be included in results. +

    +

    +If an attribute endTime from filter object is less than or equal to startTime date, an empty array will be returned. +

    +

    +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: + public +

    +

    + Privilege: + http://tizen.org/privilege/apphistory.read +

    +

    Remark : + This method is available only on mobile devices. +An attempt to call this method on other profile will result in throwing NotSupportedError exception. +

    +
    +

    Parameters:

    +
      +
    • +successCallback: + The method to call when the invocation ends successfully. +
      • +
    • +errorCallback [optional] [nullable]: + The method to call when an error occurs. +
      • +
    • +mode [optional] [nullable]: + The parameter defines a type of application usage to acquire. By default, it is set to FREQUENTLY. +
      • +
    • +filter [optional] [nullable]: + The filter for selecting period of time, from which data is accumulated. +By default, this parameter has attribute timeSpan set to 30 days. +
      • +
    • +limit [optional] [nullable]: + This parameter defines maximum count of objects ApplicationUsage in returned array. +By default, it is set to 10. +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type NotSupportedError, if this feature is not supported. +

        • +

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

        • +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +
      +
    +
    +
    +

    Code example:

     var successCallback = function(appsUsageInfo)
+ {
+   appsUsageInfo.forEach(function(auInfo)
+   {
+     console.log("ApplicationID: " + auInfo.appId + ", count: " + auInfo.totalCount +
+     ", duration: " + auInfo.totalDuration + ", last used at: " + auInfo.lastTime);
+   });
+ };
+
+ tizen.application.getAppsUsageInfo(successCallback, null, "FREQUENTLY", {timeSpan: 7}, 5);
+
    +
    +
    +

    Output example:

     ApplicationID: w5ucNMnbVi.BasicUI, count: 17, duration: 3471, last used at: Tue Aug 01 2017 12:13:06 GMT+0200 (CEST)
+ ApplicationID: org.tizen.message, count: 16, duration: 2964, last used at: Wed Aug 02 2017 08:22:14 GMT+0200 (CEST)
+ ApplicationID: api1getcap.sysinfo, count: 16, duration: 1957, last used at: Tue Aug 01 2017 12:13:03 GMT+0200 (CEST)
+ ApplicationID: org.tizen.email, count: 10, duration: 1209, last used at: Fri Jul 21 2017 10:15:09 GMT+0200 (CEST)
+ ApplicationID: org.tizen.setting, count: 5, duration: 519, last used at: Wed Aug 02 2017 06:52:51 GMT+0200 (CEST)
+
    +
    +
    addAppStatusChangeListener
    @@ -1418,8 +1579,81 @@ catch (err) +
    +

    2.3. ApplicationUsageFilter

    +
    + This interface represents filter for defining period of time, which will be used as a condition in getAppsUsageInfo method. +
    +
      dictionary ApplicationUsageFilter {
+    long? timeSpan;
+    Date? startTime;
+    Date? endTime;
+  };
    +

    + Since: + 4.0 +

    +
    +

    +The maximum retention period is 90 days. +

    +
    +
    +

    Dictionary members

    +
    +
    long? timeSpan
    +
    +
    + The attribute to store period of time, from which data is accumulated, in days. +The period of time begins timeSpan days ago and ends with current date. +
    +
    +

    +If the attribute is given, the attributes startTime and endTime of this interface are not taken into an account. +If timeSpan is greater than 90, 90 will be used instead. +

    +
    +

    + Since: + 4.0 +

    +
    +
    Date? startTime
    +
    +
    + The attribute to store the date, which is used as a lower bound for selecting data. +
    +
    +

    +If only startTime attribute is given, by default endTime is equal to the current date. +If startTime date predates the 90 days from the current time, data will be accumulated from last 90 days. +

    +
    +

    + Since: + 4.0 +

    +
    +
    Date? endTime
    +
    +
    + The attribute to store the date, which is used as an upper bound for selecting data. +
    +
    +

    +If only endTime attribute is given, data will be accumulated from 90 days ago to endTime date. +

    +
    +

    + Since: + 4.0 +

    +
    +
    +
    +
    -

    2.3. Application

    +

    2.4. Application

    This interface defines the current application's information and the basic operations (such as exit or hide) for the current application. @@ -1848,7 +2082,7 @@ app.broadcastTrustedEvent({"name": "custom_user_event"}, myTrustedCustomData);
    -

    2.4. ApplicationInformation

    +

    2.5. ApplicationInformation

    This interface defines the general information available to an installed application.
    @@ -1990,7 +2224,7 @@ be shown (such as in menus).
    -

    2.5. ApplicationContext

    +

    2.6. ApplicationContext

    This interface defines the information available about a running application. @@ -2032,7 +2266,7 @@ application.
    -

    2.6. ApplicationBatteryUsage

    +

    2.7. ApplicationBatteryUsage

    This interface defines information about battery usage of application.
    @@ -2074,8 +2308,73 @@ The attribute value scales from 0 to 1, the higher value,
    +
    +

    2.8. ApplicationUsage

    +
    + This interface defines information about usage of application. +
    +
      [NoInterfaceObject] interface ApplicationUsage {
+
+    readonly attribute ApplicationId appId;
+
+    readonly attribute unsigned long totalCount;
+
+    readonly attribute unsigned long totalDuration;
+
+    readonly attribute Date lastTime;
+  };
    +

    + Since: + 4.0 +

    +
    +

    Attributes

    +
      +
    • + readonly +ApplicationId appId
      + An attribute to store the ID of an application. +
      +

      + Since: + 4.0 +

      +
      • +
    • + readonly +unsigned long totalCount
      + An attribute to store the total number of times the application was in the foreground. +
      +

      + Since: + 4.0 +

      +
      • +
    • + readonly +unsigned long totalDuration
      + An attribute to store the total time of application usage in seconds. +
      +

      + Since: + 4.0 +

      +
      • +
    • + readonly +Date lastTime
      + An attribute to store the last time when the application was used. +
      +

      + Since: + 4.0 +

      +
      • +
    +
    +
    -

    2.7. ApplicationControlData

    +

    2.9. ApplicationControlData

    This interface defines a key/value pair used to pass data between applications through the ApplicationControl interface. @@ -2126,7 +2425,7 @@ var appControlData = new tizen.ApplicationControlData("image", [imagedata1]);
    -

    2.8. ApplicationControl

    +

    2.10. ApplicationControl

    This interface consists of an operation, URI, MIME type, and data. It describes an action to be performed by other applications @@ -2230,7 +2529,7 @@ performed by an application control.
    -

    2.9. RequestedApplicationControl

    +

    2.11. RequestedApplicationControl

    This interface has an application control information requested and passed from another application and is passed to launch other applications. The newly @@ -2381,7 +2680,7 @@ if (reqAppControl)
    -

    2.10. ApplicationCertificate

    +

    2.12. ApplicationCertificate

    This interface defines the certificate information of an installed application.
    @@ -2422,7 +2721,7 @@ if (reqAppControl)
    -

    2.11. ApplicationMetaData

    +

    2.13. ApplicationMetaData

    This interface defines the meta data of an installed application
    @@ -2463,7 +2762,7 @@ if (reqAppControl)
    -

    2.12. BatteryUsageInfoArraySuccessCallback

    +

    2.14. BatteryUsageInfoArraySuccessCallback

    This callback interface specifies a success callback that is invoked when the battery usage per application array is retrieved.
    @@ -2512,8 +2811,58 @@ This callback interface specifies a success method with an array of
    +
    +

    2.15. AppsUsageInfoArraySuccessCallback

    +
    + This callback interface specifies a success callback that is invoked when the application usage statistics array is retrieved. +
    +
      [Callback=FunctionOnly, NoInterfaceObject] interface AppsUsageInfoArraySuccessCallback {
+    void onsuccess(ApplicationUsage[] appsInfoArray);
+  };
    +

    + Since: + 4.0 +

    +
    +

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

    +
    +
    +

    Methods

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

    + Since: + 4.0 +

    +

    Remark : + An example of usage can be find at getAppsUsageInfo code example. +

    +
    +

    Parameters:

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

    2.13. ApplicationInformationArraySuccessCallback

    +

    2.16. ApplicationInformationArraySuccessCallback

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

    2.14. FindAppControlSuccessCallback

    +

    2.17. FindAppControlSuccessCallback

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

    2.15. ApplicationContextArraySuccessCallback

    +

    2.18. ApplicationContextArraySuccessCallback

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

    2.16. ApplicationControlDataArrayReplyCallback

    +

    2.19. ApplicationControlDataArrayReplyCallback

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

    2.17. SystemEventData

    +

    2.20. SystemEventData

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

    2.18. EventCallback

    +

    2.21. EventCallback

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

    2.19. StatusEventCallback

    +

    2.22. StatusEventCallback

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

    2.20. EventInfo

    +

    2.23. 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.
    @@ -3038,6 +3387,8 @@ To guarantee the running of the application on a device which has battery, decla enum ApplicationControlLaunchMode { "SINGLE", "GROUP" }; + enum ApplicationUsageMode { "RECENTLY", "FREQUENTLY" }; + [NoInterfaceObject] interface ApplicationManagerObject { readonly attribute ApplicationManager application; }; @@ -3086,11 +3437,23 @@ To guarantee the running of the application on a device which has battery, decla optional long? days, optional long? limit) raises(WebAPIException); + void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, + optional ErrorCallback? errorCallback, + optional ApplicationUsageMode? mode, + optional ApplicationUsageFilter? filter, + optional long? limit) raises(WebAPIException); + long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException); void removeAppStatusChangeListener(long watchId) raises(WebAPIException); }; + dictionary ApplicationUsageFilter { + long? timeSpan; + Date? startTime; + Date? endTime; + }; + [NoInterfaceObject] interface Application { readonly attribute ApplicationInformation appInfo; @@ -3147,6 +3510,17 @@ To guarantee the running of the application on a device which has battery, decla readonly attribute double batteryUsage; }; + [NoInterfaceObject] interface ApplicationUsage { + + readonly attribute ApplicationId appId; + + readonly attribute unsigned long totalCount; + + readonly attribute unsigned long totalDuration; + + readonly attribute Date lastTime; + }; + [Constructor(DOMString key, DOMString[] value)] interface ApplicationControlData { @@ -3203,6 +3577,10 @@ To guarantee the running of the application on a device which has battery, decla void onsuccess(ApplicationBatteryUsage[] batteryInfoArray); }; + [Callback=FunctionOnly, NoInterfaceObject] interface AppsUsageInfoArraySuccessCallback { + void onsuccess(ApplicationUsage[] appsInfoArray); + }; + [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationInformationArraySuccessCallback { void onsuccess(ApplicationInformation[] informationArray); };