Contextual Trigger: Using Context-aware Task Automation

This tutorial demonstrates how you can compose and manage rules based on context states.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Contextual Trigger API basics by learning about:

Rule creation
- 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 a notification posting or application launch.
Managing Rules
Add, enable, disable, and remove rules.
Retrieving Rules
Retrieve rules created by your application.

Creating a Rule

To compose a rule:

To use the functions and data types of the Contextual Trigger API, include the <context_trigger.h> header file in your application:
```
#include <context_trigger.h>
```
Create a rule for "Notify if the battery is not charging and either Wi-Fi or GPS is enabled when the battery level becomes too low".
Create a rule handle using the context_trigger_rule_create() function. Because both Wi-Fi and GPS conditions need not be met at the same time, the rule must be created with the CONTEXT_TRIGGER_LOGICAL_DISJUNCTION operator.
```
context_trigger_rule_h rule = NULL;
context_trigger_rule_create(CONTEXT_TRIGGER_LOGICAL_DISJUNCTION, &rule);
```

Set an optional description:

context_trigger_rule_set_description(rule, "Notify if the battery is not charging and either Wi-Fi or GPS is enabled when the battery level becomes too low");

Creating an Event

To create a CONTEXT_TRIGGER_EVENT_BATTERY event to detect battery level changes:

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 is applied to combine the attribute keys for the event. In case of the CONTEXT_TRIGGER_EVENT_BATTERY event, 2 types of contextual states are provided: CONTEXT_TRIGGER_LEVEL and CONTEXT_TRIGGER_IS_CHARGING. Because the application wants to check both if the battery level becomes too low and if the battery is not charging, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION must be applied.
Add the attribute key with the context_trigger_rule_entry_add_key() function.
The attribute key specifies the detailed comparison terms for the event.
```
// Add a CONTEXT_TRIGGER_LEVEL key
context_trigger_rule_entry_add_key(battery_event, CONTEXT_TRIGGER_LOGICAL_DISJUNCTION, CONTEXT_TRIGGER_LEVEL);

// Add a CONTEXT_TRIGGER_IS_CHARGING key
context_trigger_rule_entry_add_key(battery_event, CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, CONTEXT_TRIGGER_IS_CHARGING);
```
The application wants to check whether the battery level becomes either low, empty, or critical. For this reason, the CONTEXT_TRIGGER_LEVEL key must be added with the CONTEXT_TRIGGER_LOGICAL_DISJUNCTION logical operator.

Add the comparison operators and values for the attribute key.

Use the context_trigger_rule_entry_add_comparison_int() or context_trigger_rule_entry_add_comparison_string() function, depending on the data type.

// Add the 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 a 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);

Add the event entry to the rule:
```
context_trigger_rule_add_entry(rule, battery_event);
```
Note that a rule must include only 1 event.

Free the event:

context_trigger_rule_entry_destroy(battery_event);

Creating Conditions

To create conditions to check Wi-Fi and GPS states:

Create an event handle using the context_trigger_rule_condition_create() function:

// Create a Wi-Fi 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 a 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);

Add the attribute key with the context_trigger_rule_entry_add_key() function to specify the 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);

Add a comparison operator and value for the attribute key.
Use the context_trigger_rule_entry_add_comparison_int(), context_trigger_rule_entry_add_string(), or context_trigger_rule_entry_add() function, depending on the data type. For more information, see the Contextual Trigger guide.

In the following example, the conditions for Wi-Fi and GPS are that they are enabled.
```
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:
```
context_trigger_rule_add_entry(rule, wifi_condition);
context_trigger_rule_add_entry(rule, gps_condition);
```
Note that a condition is not mandatory and that a rule can have multiple conditions.

Free the conditions:

context_trigger_rule_entry_destroy(wifi_condition);
context_trigger_rule_entry_destroy(gps_condition);

Setting an Action

If the rule is satisfied, either an application launch or a notification posting is triggered.

To set an action:

To set an application launch request:

app_control_h app;
// Create an app control handle and set the details, such as application ID and operation

context_trigger_rule_set_action_app_control(rule, app);

The application launch request is manipulated with an app control handle. For more details, see the App Control API.

To register a notification posting request:

context_trigger_rule_set_action_notification(rule, "Battery Alert", 
                                             "Battery is getting low. To save your battery, turn off Wi-Fi or GPS", 
                                             NULL, NULL);

The Contextual Trigger API supports the basic notification type only.

Managing Rules

To manage the rules:

To register a rule:
1. Register the rule with the context_trigger_add_rule() function and acquire the rule ID:
```
int rule_id;
context_trigger_add_rule(rule, &rule_id);
```
  The application can manage the rule with its rule ID. If the application adds the same rule with a previously registered rule ID, the same rule ID is acquired.
2. Release the rule handle resource:
```
context_trigger_destroy(rule);
```
To enable and disable a rule:
- Enable the rule explicitly with its rule ID:
```
context_trigger_enable_rule(rule_id);
```
  Note that a rule can be managed only by the application that has registered the rule.
- Disable the rule with its rule ID:
```
context_trigger_disable_rule(rule_id);
```
To remove a rule:
When no longer needed, delete the rule with the context_trigger_remove_rule() function. Only disabled rules can be deleted.
```
context_trigger_remove_rule(rule_id);
```

Retrieving Rules

This use case shows how to query the application's own rule IDs, disable the enabled rules, and remove all the rules. Only the owner application can enable, disable, remove, and retrieve the rules.

To retrieve all rules:

Retrieve all the enabled rules registered by the application and disable them:

int* enabled_rule_ids;
int enabled_count;

context_trigger_get_own_rule_ids(&enabled_rule_ids, &enabled_count, NULL, NULL);

// Disable the enabled rules
int i = 0;
for (i = 0; i < enabled_count; i++) 
{
   context_trigger_disable_rule(enabled_rule_ids[i]);
}

Retrieve all the disabled rules owned by the application and remove them:

int* disabled_rule_ids;
int disabled_count;

context_trigger_get_own_rule_ids(NULL, NULL, &disabled_rule_ids, &disabled_count);

// Remove the disabled rules
for (i = 0; i < disabled_count; i++) 
{
   context_trigger_remove_rule(disabled_rule_ids[i]);
}

Free the memory allocated for the enabled and disabled rules:

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

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