Context: Detecting and Exploiting Contextual Information

The context tutorials demonstrate how to use the following features in creating Tizen mobile native applications:

Activity Recognition: Detecting Device Activities
Demonstrates how you can detect user activities.
Gesture Recognition: Detecting Device Gestures
Demonstrates how you can detect gestures performed with the device.

The context tutorials demonstrate how to use the following features in creating Tizen mobile native applications:

Activity Recognition: Detecting User Activities +
Demonstrates how you can detect user activities.
Gesture Recognition: Detecting User Gestures +
Demonstrates how you can detect gestures performed with the device.
Contextual Trigger: Context-aware Task Automation +
Demonstrates how you can automate your tasks, by monitoring contextual events and conditions detected on the device.
Contextual Trigger: Getting the Device Usage Profiles +
Demonstrates how you can retrieve the device usage profiles analyzed from the usage history of the device.

@@ -63,4 +68,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file + diff --git a/org.tizen.tutorials/html/native/context/history_tutorial_n.htm b/org.tizen.tutorials/html/native/context/history_tutorial_n.htm new file mode 100644 index 0000000..47e2d1a --- /dev/null +++ b/org.tizen.tutorials/html/native/context/history_tutorial_n.htm @@ -0,0 +1,215 @@ + + + + + + + + + + + + + Contextual History Tutorial + + + + + +

+ +

Contextual History Tutorial

+ +

+This tutorial demonstrates how to get the history profiles of the device usages, and enumerate data lists retrieved. +

+To learn about the Contextual History API features, +see the Contextual History Programming Guide. +

+This tutorial consists of the following parts: +

Getting a List of Data Records +
It will show how to get the history profiles of the device usages. + A history profile retrieved via this API is formulated as a list of data records.
Enumerating a List of Data Records +
It will show how to enumerate the records contained in the list obtained in the previous step.

+ +

Show All
Hide All

+ + +

Getting a List of Data Records

+ Hide +

+ To retrieve a contextual history profile, for example, + CONTEXT_HISTORY_FREQUENTLY_USED_APP, + a filter needs to be set to specify the data to retrieve, then the profile can be obtained + using context_history_get_list(). +

The following header needs to be included in advance. +
```
+#include <context_history.h>
+
```
+

To get a history profile, two handles, one for using the contextual history API and one for the filter, are created. +

+// Creating a handle for using the contextual history API
+context_history_h handle;
+context_history_create(&handle);
+
+// Creating a filter handle
+context_history_filter_h filter;
+context_history_filter_create(&filter);
+

The filter handle needs to be properly configured. In this example, we will get the top-5 frequently used applications, + by only considering the applications used while a headphone is connected, during the last 2 weeks (14 days). +

+// Requesting the top-5 applications
+context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_RESULT_SIZE, 5);
+
+// Limiting the time span of usage logs to 14 days
+context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_TIME_SPAN, 14);
+
+// Considering the applications used while a headphone is connected
+context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_AUDIO_JACK, CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED);
+

Then with that filter, the list of the top-5 applications can be retrieved as follows. +

+context_history_list_h list;
+
+// Getting the list of records
+context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP, filter, &list);
+
+// The filter needs to be released explicitly.
+context_history_filter_destroy(filter);
+

Enumerating a List of Data Records

+ Hide +

+ The list retrieved via + context_history_get_list() contains + a sort listed of the records, each of which consists of the pairs of keys and values. + This list can be enumerated as follows. +

In some cases, the retrieve list may contain less records than the result size set in the filter. + The actual number of records contained in the list can be checked before enumerating the list. +
```
+int size;
+context_history_list_get_count(list, &size);
+
```
+

Then, the list can be enumerated using a loop. +

+int i, count;
+char* app_id;
+context_history_record_h record;
+
+for (i = 0; i < size; ++i)
+{
+	// Getting the current record
+	context_history_list_get_current(list, &record);
+
+	// Retrieving the application ID and the total used count from the record
+	context_history_record_get_string(record, CONTEXT_HISTORY_APP_ID, &app_id);
+	context_history_record_get_int(record, CONTEXT_HISTORY_TOTAL_COUNT, &count);
+
+	// ...
+
+	// Freeing the application ID string
+	free(app_id);
+
+	// Releasing the memory occupied by the record
+	context_history_record_destroy(record);
+
+	// Iterating to the next record
+	context_history_list_move_next(list);
+}
+

After the enumeration, the list needs to be released to prevent any resource leaks. +
```
+context_history_list_destroy(list);
+
```
+
Finally, the handle should be released, + if it will not be used anymore. +
```
+context_history_destroy(handle);
+
```
+

+ +

+ + + + +

+ +

+ + + + + + + diff --git a/org.tizen.tutorials/html/native/context/trigger_tutorial_n.htm b/org.tizen.tutorials/html/native/context/trigger_tutorial_n.htm new file mode 100644 index 0000000..fd56ade --- /dev/null +++ b/org.tizen.tutorials/html/native/context/trigger_tutorial_n.htm @@ -0,0 +1,376 @@ + + + + + + + + + + + + + Contextual Trigger Tutorial + + + + + +

+ +

Contextual Trigger Tutorial

+ +

This tutorial demonstrates how to compose rules based on context states and manage them.

To learn about the Contextual Trigger API features, see the Contextual Trigger Programming Guide.

This tutorial consists of the following parts:

Composing Rules

Creating a Rule
Create a new rule and set its description.
Creating an Event
Create an event and add it to the rule.
Creating Conditions
Create conditions and add them to the rule.
Setting an Action
Set an action, such as notification posting or application launching.

Managing Rules

Adding a Rule
Add a new rule and release resources.
Enabling a Rule
Enable a rule to activate it.
Disabling a Rule
Disable a rule to deactivate it.
Removing a Rule
Remove a rule if it is no longer needed.

Retrieving Rules
Retrieve rules created by your application.

+ + +

Show All
Hide All

+ +

+
+
Creating a Rule
+ Hide +
+
+ +
To use Contextual Trigger API, your application needs to compose a rule. As a case study, the below example code illustrates how to create a rule, which can be described as "Notify if battery is not charging and either WiFi or GPS is enabled when battery level becomes too low". We will use CONTEXT_TRIGGER_EVENT_BATTERY as an event, and CONTEXT_TRIGGER_CONDITION_WIFI, and CONTEXT_TRIGGER_CONDITION_GPS as conditions.
+
1. +
  To use the contextual trigger related features of the Contextual Trigger API, include the <context_trigger.h> header file in your application:
  +
```
+#include <context_trigger.h>
+
```
  +
2. Create a rule handle using the context_trigger_rule_create() function. While creating a rule handle, the application chooses the logical operator, logical conjunction or disjunction, which will be applied to combine the conditions. WiFi and GPS conditions shouldn't be satisfied at the same time. Thus, the rule should be created with the CONTEXT_TRIGGER_LOGICAL_DISJUNCTION. +
```
+context_trigger_rule_h rule = NULL;
+context_trigger_rule_create(CONTEXT_TRIGGER_LOGICAL_DISJUNCTION, &rule);
+
```
  +
3. Your application is able to set description in human language. Note that setting description is not mandatory. +
```
+context_trigger_rule_set_description(rule, "Notify if battery is not charging and either WiFi or GPS is enabled when battery level becomes too low");
+
```
  +
+
+
+
+
Creating an Event
+ Hide +
+
+ +
Now, we need to create an CONTEXT_TRIGGER_EVENT_BATTERY event to detect battery level changes.
+
1. +
  Create an event handle using the context_trigger_rule_event_create() function.
  +
```
+context_trigger_rule_entry_h battery_event = NULL;
+context_trigger_rule_event_create(CONTEXT_TRIGGER_EVENT_BATTERY, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, &battery_event);
+
```
  +
  While creating an event handle, the application chooses the logical operator, logical conjunction or disjunction, which will be applied to combine the attribute keys for the event. In case of the event CONTEXT_TRIGGER_EVENT_BATTERY, two types of contextual states are provided: CONTEXT_TRIGGER_LEVEL and CONTEXT_TRIGGER_IS_CHARGING. And now, the application wants to check both if battery level becomes too low and if battery is not charging. Thus, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION should be applied.
  +
2. To specify detailed comparison terms for the event, the attribute key must be added in advance with the context_trigger_rule_entry_add_key() function. +
```
+// Add CONTEXT_TRIGGER_LEVEL key
+context_trigger_rule_entry_add_key(battery_event, CONTEXT_TRIGGER_LOGICAL_DISJUNCTION, CONTEXT_TRIGGER_LEVEL);
+
+// Add CONTEXT_TRIGGER_IS_CHARGING key
+context_trigger_rule_entry_add_key(battery_event, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_IS_CHARGING);
+
```
  +
  For the battery level, the application wants to check whether the battery level becomes either one of low, empty or critical. For this reason, CONTEXT_TRIGGER_LEVEL key should be added with the logical operator CONTEXT_TRIGGER_LOGICAL_DISJUNCTION.
  +
3. And then, the application can add comparison opeator and value for the attribute key with the context_trigger_rule_entry_add_comparison_int() function or the context_trigger_rule_entry_add_string() function depending on the data type. +
```
+// Add comparison values for the CONTEXT_TRIGGER_LEVEL key
+context_trigger_rule_entry_add_comparison_string(battery_event, CONTEXT_TRIGGER_LEVEL, CONTEXT_TRIGGER_EQUAL_TO, CONTEXT_TRIGGER_LOW);
+context_trigger_rule_entry_add_comparison_string(battery_event, CONTEXT_TRIGGER_LEVEL, CONTEXT_TRIGGER_EQUAL_TO, CONTEXT_TRIGGER_CRITICAL);
+context_trigger_rule_entry_add_comparison_string(battery_event, CONTEXT_TRIGGER_LEVEL, CONTEXT_TRIGGER_EQUAL_TO, CONTEXT_TRIGGER_EMPTY);
+
+// Add comparison value for the CONTEXT_TRIGGER_IS_CHARGING key
+context_trigger_rule_entry_add_comparison_int(battery_event, CONTEXT_TRIGGER_IS_CHARGING, CONTEXT_TRIGGER_EQUAL_TO, CONTEXT_TRIGGER_FALSE);
+
```
  +
4. After specifying comparison terms for the event, add the event entry to the rule. Note that a rule must include only one event. +
```
+context_trigger_rule_add_entry(rule, battery_event);
+
```
  +
5. Free the events. +
```
+context_trigger_rule_entry_destroy(battery_event);
+
```
  +
+
+

Creating Conditions

+ Hide +

+ +

The below example describes how to create conditions to check WiFi and GPS states.

Create an event handle using the context_trigger_rule_condition_create() function.

+// Create wifi condition
+context_trigger_rule_entry_h wifi_condition = NULL;
+context_trigger_rule_condition_create(CONTEXT_TRIGGER_CONDITION_WIFI, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, &wifi_condition);
+
+// Create gps condition
+context_trigger_rule_entry_h gps_condition = NULL;
+context_trigger_rule_condition_create(CONTEXT_TRIGGER_CONDITION_GPS, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, &gps_condition);
+

Like events, the attribute key first needs to be added with the context_trigger_rule_entry_add_key() function to specify comparison terms for each condition. +

+context_trigger_rule_entry_add_key(wifi_condition, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_STATE);
+context_trigger_rule_entry_add_key(gps_condition, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_STATE);
+

After that, the application can add comparison opeator and value for the attribute key with the context_trigger_rule_entry_add_comparison_int() function, the context_trigger_rule_entry_add_string() function, or the context_trigger_rule_entry_add() function depending on the data type. For more information, see the Contextual Trigger Programming Guide. In the below code example, each condition check if WiFi/GPS state is not disabled. +
```
+context_trigger_rule_entry_add_comparison_string(wifi_condition, CONTEXT_TRIGGER_STATE, CONTEXT_TRIGGER_NOT_EQUAL_TO, CONTEXT_TRIGGER_DISABLED);
+context_trigger_rule_entry_add_comparison_string(gps_condition, CONTEXT_TRIGGER_STATE, CONTEXT_TRIGGER_NOT_EQUAL_TO, CONTEXT_TRIGGER_DISABLED);
+
```
+
Add the conditions to the rule handle. Note that condition is not mandatory and that a rule can have multiple conditions. +
```
+context_trigger_rule_add_entry(rule, wifi_condition);
+context_trigger_rule_add_entry(rule, gps_condition);
+
```
+

Free the conditions. +

+context_trigger_rule_entry_destroy(wifi_condition);
+context_trigger_rule_entry_destroy(gps_condition);
+

+
+
Setting an Action
+ Hide +
+
+
An application launching or a notification posting request is set as action, which will be triggered if the rule is satisfied. The below example shows how to register a notification posting request. Note that this API supports the very basic form of notifications only.
+
```
+context_trigger_rule_set_action_notification(rule, "Battery Alert", "Battery is getting low. To save your battery, you'd better turn off WiFi or GPS", NULL, NULL);
+
```
+
Or the application is able to request application launching. An application launching request is manipulated with app control handle. Please refer to the App Control API for more details. Below example shows how to set application launching action for reference.
+
```
+app_control_h app;
+// Create app control handle and set application id, operation, and so on.
+...
+context_trigger_rule_set_action_app_control(rule, app);
+
```
+
+
+
+
Adding a Rule
+ Hide +
+
+
After creating a rule, the rule needs to be registered.
+
1. +Register the rule with the context_trigger_add_rule() function, a rule id is acquired. +
```
+int rule_id;
+context_trigger_add_rule(rule, &rule_id);
+
```
  +
  If the application adds the same rule with the previously registered one, the same rule id wil be acquired.
  +
2. +From now, the application is able to manage the rule with its rule id. The rule handle resource should be released. +
```
+context_trigger_destroy(rule);
+
```
  +
+
+
+
+
Enabling a Rule
+ Hide +
+
+
To activate the rule, the rule needs to be enabled explicitly with its rule id. Note that a rule only can be managed by the application that has registered the rule.
+
```
+context_trigger_enable_rule(rule_id);
+
```
+
+
+
+
Disabling a Rule
+ Hide +
+
+
To deactivate the rule for a while, the rule needs to be disabled with its rule id.
+
```
+context_trigger_disable_rule(rule_id);
+
```
+
+
+
+
Removing a Rule
+ Hide +
+
+
The application can delete the rule with the context_trigger_remove_rule() function if it is no longer needed.
+
```
+context_trigger_remove_rule(rule_id);
+
```
+
+

Retrieving Rules

+ Hide +

+ +

The application can retrieve all the owned rules and manage them. As mentioned, activation, deactivation, removal, and retrieval are only allowed to the owner application. The below example shows how to query its own rule IDs, deactivate enabled rules, and remove all the rules.

Retrieve all the enabled rules registered by this application and deactivate them.

+int* enabled_rule_ids;
+int enabled_count;
+
+context_trigger_get_own_rule_ids(&enabled_rule_ids, &enabled_count, NULL, NULL);
+
+// Deactivate enabled rules
+int i = 0;
+for (i = 0; i < enabled_count; i++) {
+	context_trigger_disable_rule(enabled_rule_ids[i]);
+}
+

Only deactivated rules can be deleted. After deactivating enabled rules as above, retrive all the disabled rules owned by the application to remove them. +

+int* disabled_rule_ids;
+int disabled_count;
+
+context_trigger_get_own_rule_ids(NULL, NULL, &disabled_rule_ids, &disabled_count);
+
+// Remove disabled rules
+for (i = 0; i < disabled_count; i++) {
+	context_trigger_remove_rule(disabled_rule_ids[i]);
+}
+

Finally, free the memory allocated for the enabled_rule_ids and disabled_rule_ids. +

+if (enabled_rule_ids) {
+	free(enabled_rule_ids);
+	enabled_rule_ids = NULL;
+}
+
+if (disabled_rule_ids) {
+	free(disabled_rule_ids);
+	disabled_rule_ids = NULL;
+}
+

+ + + + +

+ +

+ + + + + + + -- 2.7.4

Context: Detecting and Exploiting Contextual Information

Context: Detecting and Exploiting Contextual Information

Contextual History Tutorial

Getting a List of Data Records

Enumerating a List of Data Records

Contextual Trigger Tutorial

Creating a Rule

Creating an Event

Creating Conditions

Setting an Action

Adding a Rule

Enabling a Rule

Disabling a Rule

Removing a Rule

Retrieving Rules