From 3d61f9b89062ea317c466477c871986e4333c7a8 Mon Sep 17 00:00:00 2001 From: Somin Kim Date: Fri, 8 May 2015 20:27:12 +0900 Subject: [PATCH] [context] Updated history & trigger API's key/value descriptions, w.r.t. the MCD's review. Change-Id: I7f74340ac5062323c782bba658d815ef8e8a3ea8 Signed-off-by: Somin Kim --- org.tizen.guides/html/native/context/history_n.htm | 47 ++++++++++++---- org.tizen.guides/html/native/context/trigger_n.htm | 65 ++++------------------ 2 files changed, 46 insertions(+), 66 deletions(-) diff --git a/org.tizen.guides/html/native/context/history_n.htm b/org.tizen.guides/html/native/context/history_n.htm index a5ebb0c..6d01a14 100644 --- a/org.tizen.guides/html/native/context/history_n.htm +++ b/org.tizen.guides/html/native/context/history_n.htm @@ -39,15 +39,15 @@

The Tizen platform collects data on the device usage. Based on this data, the applications can take advantage of the user's application usage patterns through statistical analysis.

- - - - - - - - - +
Note
This feature is supported in mobile applications only.
+ + + + + + + +
Note
This feature is supported in mobile applications only.

The Contextual History API provides history data about application usage, media playback, communications, and device settings. When an application reads each type of history data, the application must set filters (mandatory and optional) to specify the necessary statistics. The following example shows how to get information about the 5 most frequently used applications from the last 30 days.

@@ -58,7 +58,7 @@ context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_TIME_SPAN, 30); // Requesting the statistics context_history_list_h list; -context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP , filter, &list); +context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP, filter, &list);

Once the context_history_list_h data handle is retrieved through the context_history_get_list() function, the attributes of each data record of the handle can be retrieved. You can use the context_history_list_get_current() function to get the current record and the context_history_record_get_string() and context_history_record_get_int() functions to access its values.

@@ -76,7 +76,6 @@ Once the context_hist Application usage history: -

CONTEXT_HISTORY_RECENTLY_USED_APP

CONTEXT_HISTORY_FREQUENTLY_USED_APP

CONTEXT_HISTORY_RARELY_USED_APP

@@ -88,7 +87,7 @@ Once the context_hist
  • Most recently or frequently used applications, in a descending order of the application use counts.
  • Most rarely used applications in removable applications, in an ascending order of the application use counts.
    • -
  • Peak time for applications, or the time period when the user most frequently uses an application during the day. +
  • Peak time for applications, or the time period when the user most frequently uses an application during the day.

    The result is a sorted list of hours of the day, in a descending order of the application use count in each one-hour time slot.

  • Common settings for applications, or the most common setting values regarding an application or any applications.
@@ -150,6 +149,7 @@ Once the context_hist History type Supported filter + Type Description @@ -157,6 +157,7 @@ Once the context_hist All types CONTEXT_HISTORY_FILTER_TIME_SPAN + Integer This filter specifies in days the time span of the data to be aggregated. For example, if the value is set to 10, the application gets the statistics from the data logged in the last 10 days.

Only positive filter values are allowed. Because of the system resources available, the maximum time span can be limited implicitly. If the value is not set, the default value of 30 days is used.

@@ -166,12 +167,14 @@ Once the context_hist CONTEXT_HISTORY_FILTER_START_TIME

CONTEXT_HISTORY_FILTER_END_TIME

+ Integer If an application requires more fine-grained controls than the time span filter, the start and end time of the period can be set as Unix epoch time in seconds using these filters. It is also possible to set the start time or the end time only. CONTEXT_HISTORY_FILTER_RESULT_SIZE + Integer This filter limits the number of data records to be retrieved. It accepts positive integers as the filter values, but if not set, it is set to 10 by default. It is possible that the aggregated result contains a smaller number of records than the filter value.

Note that this value may have no effect for some history types. For example, the common setting history types return one record for one request, thus the result size is ignored while aggregating the logs.

@@ -183,6 +186,7 @@ Once the context_hist

CONTEXT_HISTORY_FREQUENTLY_USED_APP

CONTEXT_HISTORY_FILTER_WIFI_BSSID + String Applications can get the statistics of the data logged while a specific Wi-Fi is connected, by setting the BSSID string of the target Wi-Fi AP.

The currently connected Wi-Fi AP's BSSID can be retrieved through the Wi-Fi Manager APIs. For more information, see the Wi-Fi guide.

@@ -190,6 +194,7 @@ Once the context_hist CONTEXT_HISTORY_FILTER_AUDIO_JACK + Integer Applications can get the statistics of the data logged while the headphone is connected or disconnected. The audio jack status can be either CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED or CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED. @@ -201,6 +206,7 @@ Once the context_hist

CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO

CONTEXT_HISTORY_FILTER_APP_ID + String Use the CONTEXT_HISTORY_PEAK_TIME_FOR_APP filter to compute the peak time for a specific application. Without this filter, the peak time is computed from the usage history of all applications.

In case of the peak time for music or video playbacks, these filters can be used to restrict the application that is used to play the media contents. Without this filter, playback logs from all applications are used to get the statistics.

@@ -209,6 +215,7 @@ Once the context_hist CONTEXT_HISTORY_FILTER_DAY_OF_WEEK + Integer Use this filter to get application usage patterns on weekdays or weekends. The filter value can be either CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS, CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS, or CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL. By default, data from both weekdays and weekends are used if this filter is not set. @@ -219,6 +226,7 @@ Once the context_hist

CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO

CONTEXT_HISTORY_FILTER_APP_ID + String Use this filter to retrieve the most common setting values for a specific application.

In case of music or video playback history, this filter can be used to get the common setting values when listening to music or watching videos using a specific application.

@@ -229,6 +237,7 @@ Once the context_hist CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE + Integer By default, communication frequency is computed from the call and message logs. Applications can narrow down the target data to one type of communication, call or messaging, using this filter.

The filter value can be either CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_CALL, CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_MESSAGE, or CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_ALL.

@@ -245,6 +254,7 @@ Once the context_hist History type Provided attribute + Type Description @@ -254,6 +264,7 @@ Once the context_hist

CONTEXT_HISTORY_RARELY_USED_APP

CONTEXT_HISTORY_APP_ID + String This attribute denotes the application ID.

For more information on the application IDs, see the Application Framework guide.

@@ -261,18 +272,21 @@ Once the context_hist CONTEXT_HISTORY_TOTAL_COUNT + Integer This attribute denotes how many times the application is used in the foreground. CONTEXT_HISTORY_TOTAL_DURATION + Integer This attribute denotes the time the application is being displayed in the foreground in seconds. If the application is used multiple times, it denotes the accumulated time of use. CONTEXT_HISTORY_LAST_TIME + Integer This attribute denotes when the application has been used (moved to the foreground) the last time, in Unix epoch in seconds. @@ -284,12 +298,14 @@ Once the context_hist

CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO

CONTEXT_HISTORY_HOUR_OF_DAY + Integer This attribute denotes the hour of the day. Its value is an integer from 0 to 23. CONTEXT_HISTORY_TOTAL_COUNT + Integer This attribute denotes the aggregated count of the application uses or media playbacks within the hour of the day defined with CONTEXT_HISTORY_HOUR_OF_DAY. @@ -301,18 +317,21 @@ Once the context_hist

CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO

CONTEXT_HISTORY_AUDIO_JACK + Integer This attribute denotes the most common audio jack status. The value is either CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED or CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED. CONTEXT_HISTORY_SYSTEM_VOLUME + Integer This attribute denotes the most common system volume level. CONTEXT_HISTORY_MEDIA_VOLUME + Integer This attribute denotes the most common media volume level.

For more information on the system and media volume settings, see the Sound Manager guide.

@@ -323,24 +342,28 @@ Once the context_hist CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS CONTEXT_HISTORY_ADDRESS + String This attribute denotes the contact address or a phone number. CONTEXT_HISTORY_TOTAL_COUNT + Integer This attribute denotes the total number of communications with the address defined with CONTEXT_HISTORY_ADDRESS. CONTEXT_HISTORY_TOTAL_DURATION + Integer This attribute denotes the accumulated duration of calls in seconds with the address defined with CONTEXT_HISTORY_ADDRESS. CONTEXT_HISTORY_LAST_TIME + Integer This attribute denotes when a call is connected or a message is received or sent last in Unix epoch in seconds, to or from the address defined with CONTEXT_HISTORY_ADDRESS. diff --git a/org.tizen.guides/html/native/context/trigger_n.htm b/org.tizen.guides/html/native/context/trigger_n.htm index 485e28b..85762d2 100644 --- a/org.tizen.guides/html/native/context/trigger_n.htm +++ b/org.tizen.guides/html/native/context/trigger_n.htm @@ -182,7 +182,7 @@ context_trigger_rule_entry_destroy(condition); - CONTEXT_TRIGGER_CONDITION_TIME_OF_MONTH + CONTEXT_TRIGGER_CONDITION_DAY_OF_MONTH CONTEXT_TRIGGER_DAY_OF_MONTH Integer From 1 to 31 @@ -330,33 +330,10 @@ context_trigger_rule_entry_destroy(condition); CONTEXT_TRIGGER_IN, CONTEXT_TRIGGER_OUT - CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY - CONTEXT_TRIGGER_APP_ID - String - Application ID - - - CONTEXT_TRIGGER_RANK - Integer - Positive integer - - - CONTEXT_TRIGGER_TOTAL_COUNT - Integer - Non-negative integer - - - CONTEXT_TRIGGER_AVERAGE_COUNT - Integer - Non-negative integer - - - CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY - CONTEXT_TRIGGER_APP_ADDRESS - String - Phone number - - + + CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY +

CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY

+ CONTEXT_TRIGGER_RANK Integer Positive integer @@ -367,12 +344,7 @@ context_trigger_rule_entry_destroy(condition); Non-negative integer - CONTEXT_TRIGGER_AVERAGE_COUNT - Integer - Non-negative integer - - - + CONTEXT_TRIGGER_CONDITION_MUSIC_PLAYBACK_FREQUENCY

CONTEXT_TRIGGER_CONDITION_VIDEO_PLAYBACK_FREQUENCY

@@ -380,11 +352,6 @@ context_trigger_rule_entry_destroy(condition); Integer Non-negative integer - - CONTEXT_TRIGGER_AVERAGE_COUNT - Integer - Non-negative integer - @@ -467,28 +434,18 @@ context_trigger_rule_entry_add_comparison_int(condition, CONTEXT_TRIGGER_RANK, C - CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY + CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY CONTEXT_TRIGGER_APP_ID String Application ID - CONTEXT_TRIGGER_RANK - Integer - Positive integer - - - CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY + CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY CONTEXT_TRIGGER_ADDRESS String Phone number - CONTEXT_TRIGGER_RANK - Integer - Positive integer - - CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY

CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY

@@ -568,7 +525,7 @@ context_trigger_rule_set_action_notification(disjunction_rule, ...);
  • Combining attributes into an event or condition

    Some event and condition items provide multiple attributes. The logical connection between attributes must be set properly to fulfill the requirement. For example, when you use CONTEXT_TRIGGER_EVENT_ON_TIME to define a rule "at 4 PM every Monday", the comparisons regarding the 2 attributes, CONTEXT_TRIGGER_TIME_OF_DAY and CONTEXT_TRIGGER_DAY_OF_WEEK must be satisfied together.

    -

    On the contrary, using CONTEXT_TRIGGER_APP_USE_FREQUENCY, if you want to check whether a specific application belongs to the 5 most frequently used applications, or the application was used at least 10 times per day on average, the both comparisons against CONTEXT_TRIGGER_RANK and CONTEXT_TRIGGER_AVERAGE_COUNT need to be connected by logical disjunction.

    +

    On the contrary, using CONTEXT_TRIGGER_APP_USE_FREQUENCY, if you want to check whether a specific application belongs to the 5 most frequently used applications, or the application was used at least 10 times, the both comparisons against CONTEXT_TRIGGER_RANK and CONTEXT_TRIGGER_TOTAL_COUNT need to be connected by logical disjunction.

    The following example illustrates the cases described above:

    @@ -586,8 +543,8 @@ context_trigger_rule_condition_create(CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENC
 context_trigger_rule_entry_add_option_string(app_condition, CONTEXT_TRIGGER_APP_ID, /* Application ID */);
 context_trigger_rule_entry_add_key(app_condition, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_RANK);
 context_trigger_rule_entry_add_comparison_int(app_condition, CONTEXT_TRIGGER_RANK, CONTEXT_TRIGGER_LESS_THAN_OR_EQUAL_TO, 5);
-context_trigger_rule_entry_add_key(app_condition, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_AVERAGE_COUNT);
-context_trigger_rule_entry_add_comparison_int(app_condition, CONTEXT_TRIGGER_AVERAGE_COUNT, CONTEXT_TRIGGER_GREATER_THAN_OR_EQUAL_TO, 10);
+context_trigger_rule_entry_add_key(app_condition, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_TOTAL_COUNT);
+context_trigger_rule_entry_add_comparison_int(app_condition, CONTEXT_TRIGGER_TOTAL_COUNT, CONTEXT_TRIGGER_GREATER_THAN_OR_EQUAL_TO, 10);
  • Combining comparisons into an attribute -- 2.7.4