The contextual trigger API provides a way to define rules, each of which can trigger a specified action when the rule is satisfied.

Required Header

#include <context_trigger.h>

Overview

The contextual trigger API provides a way to define trigger rules, each of which launches an application or posts a notification if it is satisfied.

To use this API, an application first needs to assemble a rule, which consists of the following three components:

An Event: The contextual trigger engine starts to verify if the rule is satisfied, when the event occurs. As the name suggests, it is literally an event that can be recognized in the device, e.g., changes of setting values or connections of peripherals. See context_trigger_event_e for all available event items.
A Set of Conditions: If the event occurs, the trigger engine checks whether the conditions are satisfied or not. The application can choose the way of combining conditions, i.e., logical conjunction or disjunction. In case of logical conjunction, for example, the set of conditions is true if and only if all conditions are true. If no condition is set, i.e., the set of conditions is empty, the trigger engine considers the set is satisfied, regardless of the current context. See context_trigger_condition_e for all available condition items.
An Action: If the conditions are satisfied, a designated action will be triggered. The action can be an app launching request or a notification posting request.

Note that, a rule only can be managed by the application that has registered the rule.

If the rule is not required anymore, it can be disabled and removed from the engine. Note that, rule activation, deactivation, and removals are only allowed to the owner application, which has registered the rule to the trigger engine. In the below example, the application queries its own rule IDs, deactivates enabled rules, and removes all rules from the trigger engine.

For more details, please see the programming guide and the tutorial.

Related Features

Some of the event and condition items in this API are related with one of the following features:

It is recommended to design feature related code in your application for reliability.
For your convenience, context_trigger_rule_event_is_supported() and context_trigger_rule_condition_is_supported() are provided. Applications can use these functions to check the availability of a necessary event or condition, before registering a rule, to be sure that the rule is valid in the current device.

In general, you can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application. To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK. More details on featuring your application can be found from Feature Element.

Functions
int	context_trigger_add_rule (context_trigger_rule_h rule, int *rule_id)
	Registers a rule.
int	context_trigger_remove_rule (int rule_id)
	Removes a rule.
int	context_trigger_enable_rule (int rule_id)
	Enables a rule.
int	context_trigger_disable_rule (int rule_id)
	Disables a rule.
int	context_trigger_get_own_rule_ids (int *enabled_rule_ids, int enabled_rule_count, int *disabled_rule_ids, int disabled_rule_count)
	Gets the IDs of the rules owned by the current application.
int	context_trigger_get_rule_by_id (int rule_id, context_trigger_rule_h *rule)
	Gets a rule stored in the system by rule ID.
int	context_trigger_rule_create (context_trigger_logical_type_e logical_type, context_trigger_rule_h *rule)
	Creates an empty rule.
int	context_trigger_rule_destroy (context_trigger_rule_h rule)
	Releases the resources occupied by a rule handle.
int	context_trigger_rule_add_entry (context_trigger_rule_h rule, context_trigger_rule_entry_h entry)
	Adds an event or a condition to a rule.
int	context_trigger_rule_set_action_app_control (context_trigger_rule_h rule, app_control_h app_control)
	Sets a app launching request as the action of a rule.
int	context_trigger_rule_set_action_notification (context_trigger_rule_h rule, const char title, const char content, const char *icon_path, app_control_h app_control)
	Sets a notification posting request as the action of a rule.
int	context_trigger_rule_set_description (context_trigger_rule_h rule, const char *description)
	Sets the description of a rule.
int	context_trigger_rule_get_description (context_trigger_rule_h rule, char **description)
	Gets the description of a rule.
int	context_trigger_rule_event_create (context_trigger_event_e event_item, context_trigger_logical_type_e logical_type, context_trigger_rule_entry_h *entry)
	Creates an event entry.
int	context_trigger_rule_event_is_supported (context_trigger_event_e event_item, bool *supported)
	Checks whether a contextual event is supported in the current device.
int	context_trigger_rule_condition_create (context_trigger_condition_e condition_item, context_trigger_logical_type_e logical_type, context_trigger_rule_entry_h *entry)
	Creates a condition entry.
int	context_trigger_rule_condition_is_supported (context_trigger_condition_e condition_item, bool *supported)
	Checks whether a contextual condition is supported in the current device.
int	context_trigger_rule_entry_destroy (context_trigger_rule_entry_h entry)
	Releases the resource occupied by an entry.
int	context_trigger_rule_entry_add_option_int (context_trigger_rule_entry_h entry, const char *option_key, int value)
	Sets an integer type option to an event or condition entry.
int	context_trigger_rule_entry_add_option_string (context_trigger_rule_entry_h entry, const char option_key, const char value)
	Sets a string type option to an event or condition entry.
int	context_trigger_rule_entry_add_option (context_trigger_rule_entry_h entry, const char option_key, const char event_data_key)
	Sets an option to a condition entry, which references an attribute that will be extracted from the event.
int	context_trigger_rule_entry_add_key (context_trigger_rule_entry_h entry, context_trigger_logical_type_e logical_type, const char *key)
	Adds an attribute key to an entry.
int	context_trigger_rule_entry_add_comparison_int (context_trigger_rule_entry_h entry, const char key, const char comp_operator, int value)
	Adds a comparison between an attribute key and an integer.
int	context_trigger_rule_entry_add_comparison_string (context_trigger_rule_entry_h entry, const char key, const char comp_operator, const char *value)
	Adds a comparison between an attribute key and a string.
int	context_trigger_rule_entry_add_comparison (context_trigger_rule_entry_h entry, const char key, const char comp_operator, const char *event_data_key)
	Adds a comparison between an attribute of a condition and an attribute extracted from the event.
int	context_trigger_custom_register (const char name, const char attr_template)
	Defines a custom contextual data item with its template.
int	context_trigger_custom_unregister (const char *name)
	Removes a defined custom contextual data item.
int	context_trigger_custom_publish (const char name, const char fact)
	Publishes an instance of a defined custom contextual data.
int	context_trigger_rule_custom_event_create (const char event_item, const char provider, context_trigger_logical_type_e logical_type, context_trigger_rule_entry_h *entry)
	Creates an event entry with custom event, instead of predefined event item context_trigger_event_e.
int	context_trigger_rule_custom_condition_create (const char condition_item, const char provider, context_trigger_logical_type_e logical_type, context_trigger_rule_entry_h *entry)
	Creates a condition entry with custom condition, instead of predefined condition item context_trigger_condition_e.
Typedefs
typedef struct _context_trigger_rule_s *	context_trigger_rule_h
	Trigger rule editing handle.
typedef struct _context_trigger_rule_entry_s *	context_trigger_rule_entry_h
	Editing an event or a condition, which is added to a rule using handle.
Defines
#define	CONTEXT_TRIGGER_EQUAL_TO "=="
	Definition for the operator "is equal to".
#define	CONTEXT_TRIGGER_NOT_EQUAL_TO "!="
	Definition for the operator "is not equal to".
#define	CONTEXT_TRIGGER_GREATER_THAN ">"
	Definition for the operator "is greater than".
#define	CONTEXT_TRIGGER_GREATER_THAN_OR_EQUAL_TO ">="
	Definition for the operator "is greater than or equal to".
#define	CONTEXT_TRIGGER_LESS_THAN "<"
	Definition for the operator "is less than".
#define	CONTEXT_TRIGGER_LESS_THAN_OR_EQUAL_TO "<="
	Definition for the operator "is less than or equal to".
#define	CONTEXT_TRIGGER_TRUE 1
	Definition for the logical true.
#define	CONTEXT_TRIGGER_FALSE 0
	Definition for the logical false.
#define	CONTEXT_TRIGGER_TIME_OF_DAY "TimeOfDay"
	Definition for the attribute key denoting "time of day".
#define	CONTEXT_TRIGGER_DAY_OF_WEEK "DayOfWeek"
	Definition for the attribute key denoting "day of week".
#define	CONTEXT_TRIGGER_DAY_OF_MONTH "DayOfMonth"
	Definition for the attribute key denoting "day of month".
#define	CONTEXT_TRIGGER_IS_CONNECTED "IsConnected"
	Definition for the attribute key denoting boolean states of "is connected".
#define	CONTEXT_TRIGGER_IS_CHARGING "IsCharging"
	Definition for the attribute key denoting boolean states of "is charging".
#define	CONTEXT_TRIGGER_IS_ENABLED "IsEnabled"
	Definition for the attribute key denoting boolean states of "is enabled".
#define	CONTEXT_TRIGGER_LEVEL "Level"
	Definition for the attribute key denoting "level".
#define	CONTEXT_TRIGGER_STATE "State"
	Definition for the attribute key denoting "state".
#define	CONTEXT_TRIGGER_BSSID "BSSID"
	Definition for the attribute key denoting "BSSID".
#define	CONTEXT_TRIGGER_TYPE "Type"
	Definition for the attribute key denoting "type".
#define	CONTEXT_TRIGGER_EVENT "Event"
	Definition for the attribute key denoting "event".
#define	CONTEXT_TRIGGER_ACCURACY "Accuracy"
	Definition for the attribute key denoting "accuracy".
#define	CONTEXT_TRIGGER_MEDIUM "Medium"
	Definition for the attribute key denoting "medium".
#define	CONTEXT_TRIGGER_PLACE_ID "PlaceId"
	Definition for the attribute key denoting "place id".
#define	CONTEXT_TRIGGER_APP_ID "AppId"
	Definition for the attribute key denoting "application id".
#define	CONTEXT_TRIGGER_ADDRESS "Address"
	Definition for the attribute key denoting "address".
#define	CONTEXT_TRIGGER_RANK "Rank"
	Definition for the attribute key denoting "rank".
#define	CONTEXT_TRIGGER_TOTAL_COUNT "TotalCount"
	Definition for the attribute key denoting "total count".
#define	CONTEXT_TRIGGER_MON "Mon"
	Definition for the attribute value denoting Monday.
#define	CONTEXT_TRIGGER_TUE "Tue"
	Definition for the attribute value denoting Tuesday.
#define	CONTEXT_TRIGGER_WED "Wed"
	Definition for the attribute value denoting Wednesday.
#define	CONTEXT_TRIGGER_THU "Thu"
	Definition for the attribute value denoting Thursday.
#define	CONTEXT_TRIGGER_FRI "Fri"
	Definition for the attribute value denoting Friday.
#define	CONTEXT_TRIGGER_SAT "Sat"
	Definition for the attribute value denoting Saturday.
#define	CONTEXT_TRIGGER_SUN "Sun"
	Definition for the attribute value denoting Sunday.
#define	CONTEXT_TRIGGER_WEEKDAY "Weekday"
	Definition for the attribute value denoting Weekdays.
#define	CONTEXT_TRIGGER_WEEKEND "Weekend"
	Definition for the attribute value denoting Weekends.
#define	CONTEXT_TRIGGER_EMPTY "Empty"
	Definition for the attribute value denoting the "empty" state.
#define	CONTEXT_TRIGGER_CRITICAL "Critical"
	Definition for the attribute value denoting the "critical" state.
#define	CONTEXT_TRIGGER_LOW "Low"
	Definition for the attribute value denoting the "low" state.
#define	CONTEXT_TRIGGER_NORMAL "Normal"
	Definition for the attribute value denoting the "normal" state.
#define	CONTEXT_TRIGGER_HIGH "High"
	Definition for the attribute value denoting the "high" state.
#define	CONTEXT_TRIGGER_FULL "Full"
	Definition for the attribute value denoting the "full" state.
#define	CONTEXT_TRIGGER_DISABLED "Disabled"
	Definition for the attribute value denoting the "disabled" state.
#define	CONTEXT_TRIGGER_SEARCHING "Searching"
	Definition for the attribute value denoting the "searching" state.
#define	CONTEXT_TRIGGER_CONNECTING "Connecting"
	Definition for the attribute value denoting the "connecting" state.
#define	CONTEXT_TRIGGER_CONNECTED "Connected"
	Definition for the attribute value denoting the "connected" state.
#define	CONTEXT_TRIGGER_UNCONNECTED "Unconnected"
	Definition for the attribute value denoting the "unconnected" state.
#define	CONTEXT_TRIGGER_IDLE "Idle"
	Definition for the attribute value denoting the "idle" state.
#define	CONTEXT_TRIGGER_VOICE "Voice"
	Definition for the attribute value denoting the "voice" type.
#define	CONTEXT_TRIGGER_VIDEO "Video"
	Definition for the attribute value denoting the "video" type.
#define	CONTEXT_TRIGGER_HEADSET "Headset"
	Definition for the attribute value denoting the "headset" type.
#define	CONTEXT_TRIGGER_BLUETOOTH "Bluetooth"
	Definition for the attribute value denoting the "bluetooth" type.
#define	CONTEXT_TRIGGER_RECEIVED "Received"
	Definition for the attribute value denoting the "received" event.
#define	CONTEXT_TRIGGER_SENT "Sent"
	Definition for the attribute value denoting the "sent" event.
#define	CONTEXT_TRIGGER_SMS "SMS"
	Definition for the attribute value denoting the "SMS" type.
#define	CONTEXT_TRIGGER_MMS "MMS"
	Definition for the attribute value denoting the "MMS" type.
#define	CONTEXT_TRIGGER_MY_PROFILE "MyProfile"
	Definition for the attribute value denoting the "my profile" view.
#define	CONTEXT_TRIGGER_PERSON "Person"
	Definition for the attribute value denoting the "person" view.
#define	CONTEXT_TRIGGER_CHANGED "Changed"
	Definition for the attribute value denoting the "Changed" event.
#define	CONTEXT_TRIGGER_DETECTED "Detected"
	Definition for the attribute value denoting the "detected" event.
#define	CONTEXT_TRIGGER_IN "In"
	Definition for the attribute value denoting the "in" event.
#define	CONTEXT_TRIGGER_OUT "Out"
	Definition for the attribute value denoting the "out" event.

Define Documentation

#define CONTEXT_TRIGGER_ACCURACY "Accuracy"

Definition for the attribute key denoting "accuracy".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_ADDRESS "Address"

Definition for the attribute key denoting "address".

This can be used as a key of context_trigger_rule_entry_add_option_string(), or context_trigger_rule_entry_add_comparison_string().
See the programming guide and CAPI_CONTEXT_TRIGGER_MODULE_OPTION_FORMAT to find the corresponding items.

Since :: 2.4

#define CONTEXT_TRIGGER_APP_ID "AppId"

Definition for the attribute key denoting "application id".

This can be used as a key of context_trigger_rule_entry_add_option_string().
See the programming guide to find the corresponding trigger events.

Since :: 2.4

#define CONTEXT_TRIGGER_BLUETOOTH "Bluetooth"

Definition for the attribute value denoting the "bluetooth" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_BSSID "BSSID"

Definition for the attribute key denoting "BSSID".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_CHANGED "Changed"

Definition for the attribute value denoting the "Changed" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 3.0

#define CONTEXT_TRIGGER_CONNECTED "Connected"

Definition for the attribute value denoting the "connected" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_CONNECTING "Connecting"

Definition for the attribute value denoting the "connecting" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_CRITICAL "Critical"

Definition for the attribute value denoting the "critical" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_DAY_OF_MONTH "DayOfMonth"

Definition for the attribute key denoting "day of month".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
The valid range of the corresponding right operands is from 1 to 31.

Since :: 2.4

#define CONTEXT_TRIGGER_DAY_OF_WEEK "DayOfWeek"

Definition for the attribute key denoting "day of week".

This can be used as a key of context_trigger_rule_entry_add_option_string(), or left operands of context_trigger_rule_entry_add_comparison_string().
As the right operands of this attribute, one of the following values are allowed: CONTEXT_TRIGGER_MON, CONTEXT_TRIGGER_TUE, CONTEXT_TRIGGER_WED, CONTEXT_TRIGGER_THU, CONTEXT_TRIGGER_FRI, CONTEXT_TRIGGER_SAT, CONTEXT_TRIGGER_SUN, CONTEXT_TRIGGER_WEEKDAY, and CONTEXT_TRIGGER_WEEKEND.

Since :: 2.4

#define CONTEXT_TRIGGER_DETECTED "Detected"

Definition for the attribute value denoting the "detected" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_DISABLED "Disabled"

Definition for the attribute value denoting the "disabled" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_EMPTY "Empty"

Definition for the attribute value denoting the "empty" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_EQUAL_TO "=="

Definition for the operator "is equal to".

This can be used as operators of context_trigger_rule_entry_add_comparison_int() and context_trigger_rule_entry_add_comparison_string().

Since :: 2.4

#define CONTEXT_TRIGGER_EVENT "Event"

Definition for the attribute key denoting "event".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_FALSE 0

Definition for the logical false.

This can be used as right operands of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_FRI "Fri"

Definition for the attribute value denoting Friday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_FULL "Full"

Definition for the attribute value denoting the "full" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_GREATER_THAN ">"

Definition for the operator "is greater than".

This can be used as operators of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_GREATER_THAN_OR_EQUAL_TO ">="

Definition for the operator "is greater than or equal to".

This can be used as operators of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_HEADSET "Headset"

Definition for the attribute value denoting the "headset" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_HIGH "High"

Definition for the attribute value denoting the "high" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_IDLE "Idle"

Definition for the attribute value denoting the "idle" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_IN "In"

Definition for the attribute value denoting the "in" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_IS_CHARGING "IsCharging"

Definition for the attribute key denoting boolean states of "is charging".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
As the right operands of this attribute, one of the following values are allowed: CONTEXT_TRIGGER_TRUE and CONTEXT_TRIGGER_FALSE.

Since :: 2.4

#define CONTEXT_TRIGGER_IS_CONNECTED "IsConnected"

Definition for the attribute key denoting boolean states of "is connected".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
As the right operands of this attribute, one of the following values are allowed: CONTEXT_TRIGGER_TRUE and CONTEXT_TRIGGER_FALSE.

Since :: 2.4

#define CONTEXT_TRIGGER_IS_ENABLED "IsEnabled"

Definition for the attribute key denoting boolean states of "is enabled".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
As the right operands of this attribute, one of the following values are allowed: CONTEXT_TRIGGER_TRUE and CONTEXT_TRIGGER_FALSE.

Since :: 2.4

#define CONTEXT_TRIGGER_LESS_THAN "<"

Definition for the operator "is less than".

This can be used as operators of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_LESS_THAN_OR_EQUAL_TO "<="

Definition for the operator "is less than or equal to".

This can be used as operators of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_LEVEL "Level"

Definition for the attribute key denoting "level".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands values.

Since :: 2.4

#define CONTEXT_TRIGGER_LOW "Low"

Definition for the attribute value denoting the "low" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_MEDIUM "Medium"

Definition for the attribute key denoting "medium".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_MMS "MMS"

Definition for the attribute value denoting the "MMS" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_MON "Mon"

Definition for the attribute value denoting Monday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_MY_PROFILE "MyProfile"

Definition for the attribute value denoting the "my profile" view.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 3.0

#define CONTEXT_TRIGGER_NORMAL "Normal"

Definition for the attribute value denoting the "normal" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_NOT_EQUAL_TO "!="

Definition for the operator "is not equal to".

This can be used as operators of context_trigger_rule_entry_add_comparison_int() and context_trigger_rule_entry_add_comparison_string().

Since :: 2.4

#define CONTEXT_TRIGGER_OUT "Out"

Definition for the attribute value denoting the "out" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_PERSON "Person"

Definition for the attribute value denoting the "person" view.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 3.0

#define CONTEXT_TRIGGER_PLACE_ID "PlaceId"

Definition for the attribute key denoting "place id".

This can be used as a key of context_trigger_rule_entry_add_option_int().
See the programming guide to find the corresponding trigger events.

Since :: 2.4

#define CONTEXT_TRIGGER_RANK "Rank"

Definition for the attribute key denoting "rank".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_RECEIVED "Received"

Definition for the attribute value denoting the "received" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_SAT "Sat"

Definition for the attribute value denoting Saturday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_SEARCHING "Searching"

Definition for the attribute value denoting the "searching" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_SENT "Sent"

Definition for the attribute value denoting the "sent" event.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_SMS "SMS"

Definition for the attribute value denoting the "SMS" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_STATE "State"

Definition for the attribute key denoting "state".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_SUN "Sun"

Definition for the attribute value denoting Sunday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_THU "Thu"

Definition for the attribute value denoting Thursday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_TIME_OF_DAY "TimeOfDay"

Definition for the attribute key denoting "time of day".

This can be used as a key of context_trigger_rule_entry_add_option_string(), or left operands of context_trigger_rule_entry_add_comparison_int().
When being used as option, it is time interval of the day. For example, "13-15" denotes "from 1 PM to 3 PM". When being used with CONTEXT_TRIGGER_EVENT_TIME or CONTEXT_TRIGGER_CONDITION_TIME, it's unit is "minute", the valid range of the corresponding right operands is thus from 0 (12:00 AM) to 1439 (11:59 PM).

Since :: 2.4

#define CONTEXT_TRIGGER_TOTAL_COUNT "TotalCount"

Definition for the attribute key denoting "total count".

This can be used as left operands of context_trigger_rule_entry_add_comparison_int().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_TRUE 1

Definition for the logical true.

This can be used as right operands of context_trigger_rule_entry_add_comparison_int().

Since :: 2.4

#define CONTEXT_TRIGGER_TUE "Tue"

Definition for the attribute value denoting Tuesday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_TYPE "Type"

Definition for the attribute key denoting "type".

This can be used as left operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find available right operands.

Since :: 2.4

#define CONTEXT_TRIGGER_UNCONNECTED "Unconnected"

Definition for the attribute value denoting the "unconnected" state.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_VIDEO "Video"

Definition for the attribute value denoting the "video" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_VOICE "Voice"

Definition for the attribute value denoting the "voice" type.

This can be used as right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_WED "Wed"

Definition for the attribute value denoting Wednesday.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_WEEKDAY "Weekday"

Definition for the attribute value denoting Weekdays.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

#define CONTEXT_TRIGGER_WEEKEND "Weekend"

Definition for the attribute value denoting Weekends.

This can be used as a value of context_trigger_rule_entry_add_option_string() or right operands of context_trigger_rule_entry_add_comparison_string().
See the programming guide to find the corresponding option keys or left operand attribute keys.

Since :: 2.4

Typedef Documentation

typedef struct _context_trigger_rule_entry_s* context_trigger_rule_entry_h

Editing an event or a condition, which is added to a rule using handle.

Since :: 2.4

typedef struct _context_trigger_rule_s* context_trigger_rule_h

Trigger rule editing handle.

Since :: 2.4

Enumeration Type Documentation

enum context_trigger_condition_e

Enumeration for condition types.

Since :: 2.4

Enumerator:

CONTEXT_TRIGGER_CONDITION_TIME	Time of day
CONTEXT_TRIGGER_CONDITION_BATTERY	Battery level
CONTEXT_TRIGGER_CONDITION_CHARGER	Charger connection
CONTEXT_TRIGGER_CONDITION_GPS	GPS state
CONTEXT_TRIGGER_CONDITION_HEADPHONE	Headphone connection
CONTEXT_TRIGGER_CONDITION_USB	USB connection
CONTEXT_TRIGGER_CONDITION_WIFI	WiFi state Privilege: http://tizen.org/privilege/network.get
CONTEXT_TRIGGER_CONDITION_POWER_SAVING_MODE	Power saving mode setting
CONTEXT_TRIGGER_CONDITION_CALL	Call state Privilege: http://tizen.org/privilege/telephony
CONTEXT_TRIGGER_CONDITION_APP_USE_FREQUENCY	Frequency of app use Privilege: http://tizen.org/privilege/apphistory.read
CONTEXT_TRIGGER_CONDITION_COMMUNICATION_FREQUENCY	Frequency of communication via call or message Privilege: http://tizen.org/privilege/callhistory.read
CONTEXT_TRIGGER_CONDITION_MUSIC_PLAYBACK_FREQUENCY	Frequency of music playback Privilege: http://tizen.org/privilege/mediahistory.read
CONTEXT_TRIGGER_CONDITION_VIDEO_PLAYBACK_FREQUENCY	Frequency of video playback Privilege: http://tizen.org/privilege/mediahistory.read

enum context_trigger_error_e

Enumeration for context trigger API of error codes.

Since :: 2.4

Enumerator:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid function parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED	Permission denied
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Not supported
CONTEXT_TRIGGER_ERROR_NO_DATA	No data
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_RULE_ENABLED	Rule is enabled
CONTEXT_TRIGGER_ERROR_RULE_NOT_ENABLED	Rule is not enabled
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule
CONTEXT_TRIGGER_ERROR_RULE_NOT_EXIST	Rule does not exist
CONTEXT_TRIGGER_ERROR_DATA_EXIST	Data exist (Since 3.0)
CONTEXT_TRIGGER_ERROR_INVALID_DATA	Invalid data (Since 3.0)

enum context_trigger_event_e

Enumeration for event types.

Since :: 2.4

Enumerator:

CONTEXT_TRIGGER_EVENT_TIME	At certain times of day and days of week Privilege: http://tizen.org/privilege/alarm.set
CONTEXT_TRIGGER_EVENT_BATTERY	Battery level changed
CONTEXT_TRIGGER_EVENT_CHARGER	Charger connected/disconnected
CONTEXT_TRIGGER_EVENT_GPS	GPS state changed
CONTEXT_TRIGGER_EVENT_HEADPHONE	Headphone connected/disconnected
CONTEXT_TRIGGER_EVENT_USB	USB connected/disconnected
CONTEXT_TRIGGER_EVENT_WIFI	WiFi state changed Privilege: http://tizen.org/privilege/network.get
CONTEXT_TRIGGER_EVENT_POWER_SAVING_MODE	Power saving mode enabled/disabled
CONTEXT_TRIGGER_EVENT_CALL	Call state changed Privilege: http://tizen.org/privilege/telephony
CONTEXT_TRIGGER_EVENT_EMAIL	Email sent/received
CONTEXT_TRIGGER_EVENT_MESSAGE	Message sent/received Privilege: http://tizen.org/privilege/message.read
CONTEXT_TRIGGER_EVENT_CONTACTS	Contacts changed (Since 3.0) Privilege: http://tizen.org/privilege/contact.read
CONTEXT_TRIGGER_EVENT_ACTIVITY_STATIONARY	'Stationary' activity detected
CONTEXT_TRIGGER_EVENT_ACTIVITY_WALKING	'Walking' activity detected
CONTEXT_TRIGGER_EVENT_ACTIVITY_RUNNING	'Running' activity detected
CONTEXT_TRIGGER_EVENT_ACTIVITY_IN_VEHICLE	'In vehicle' activity detected
CONTEXT_TRIGGER_EVENT_PLACE	Get in/out to/from a specific user place Privilege: http://tizen.org/privilege/location

enum context_trigger_logical_type_e

Enumeration for logical operation types.

Since :: 2.4

Enumerator:

CONTEXT_TRIGGER_LOGICAL_CONJUNCTION	Logical conjunction
CONTEXT_TRIGGER_LOGICAL_DISJUNCTION	Logical disjunction

Function Documentation

int context_trigger_add_rule	(	context_trigger_rule_h	rule,
		int *	rule_id
	)

Registers a rule.

Using this, applications can register a rule and get the ID of the registered rule.
A rule can only be enabled, disabled, or removed by the application that has registered the rule.

Since :: 2.4

Remarks:: When registering a new rule, regarding the event and condition items used to compose the rule, the application may require one or more privileges. For details, see context_trigger_rule_event_create() and context_trigger_rule_condition_create().

Parameters:

[in]	rule	The rule to register
[out]	rule_id	The ID assigned to the rule

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED	Permission denied
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event/condition contained
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

See also:: context_trigger_remove_rule()

int context_trigger_custom_publish	(	const char *	name,
		const char *	fact
	)

Publishes an instance of a defined custom contextual data.

Using this, an application can publish the latest value of a custom data defined by the same application. The published data instance triggers the evaluation process of the trigger rules that use the data in their event part. If a rule uses the custom data as a condition, the last known value is referenced. See the programming guide to find the JSON format for the fact.

Since :: 3.0

Remarks:: Corresponding contextual data can only be published by the application that registered it.

Parameters:

[in]	name	The name of custom contextual data item
[in]	fact	The contextual data to be provided in JSON format

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event/condition contained
CONTEXT_TRIGGER_ERROR_INVALID_DATA	Invalid data

int context_trigger_custom_register	(	const char *	name,
		const char *	attr_template
	)

Defines a custom contextual data item with its template.

A contextual data item can be used as an event or a condition of other applications' trigger rules, in addition to predefined context_trigger_event_e and context_trigger_condition_e. See the programming guide to find the JSON format for the attr_template.

Since :: 3.0

Parameters:

[in]	name	The name of a custom contextual data item
[in]	attr_template	The attribute template which explains contextual data schema in JSON format

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_DATA_EXIST	Data exist
CONTEXT_TRIGGER_ERROR_INVALID_DATA	Invalid data

See also:: context_trigger_custom_unregister()

int context_trigger_custom_unregister ( const char * name )

Removes a defined custom contextual data item.

Since :: 3.0

Remarks:: A custom event/condition data item can only be removed by the application that registered it.

Parameters:

[in] name The name of a custom contextual data item

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event/condition item

See also:: context_trigger_custom_register()

int context_trigger_disable_rule ( int rule_id )

Disables a rule.

This deactivates the rule designated by the rule_id, which is owned by the application.

Since :: 2.4

Parameters:

[in] rule_id The ID of the rule to be disabled

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_RULE_NOT_ENABLED	Rule is not enabled
CONTEXT_TRIGGER_ERROR_RULE_NOT_EXIST	Rule does not exist

See also:: context_trigger_enable_rule()

int context_trigger_enable_rule ( int rule_id )

Enables a rule.

This activates the rule designated by the rule_id, which is owned by the application.

Since :: 2.4

Parameters:

[in] rule_id The ID of the rule to be enabled

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event/condition contained
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_RULE_ENABLED	Rule is enabled already
CONTEXT_TRIGGER_ERROR_RULE_NOT_EXIST	Rule does not exist

See also:: context_trigger_disable_rule()

int context_trigger_get_own_rule_ids	(	int **	enabled_rule_ids,
		int *	enabled_rule_count,
		int **	disabled_rule_ids,
		int *	disabled_rule_count
	)

Gets the IDs of the rules owned by the current application.

Since :: 2.4

Remarks:: The arrays enabled_rule_ids and disabled_rule_ids must be released using free().

Parameters:

[out]	enabled_rule_ids	The IDs of the active rules
[out]	enabled_rule_count	The number of the active rules
[out]	disabled_rule_ids	The IDs of the inactive rules
[out]	disabled_rule_count	The number of the inactive rules

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed

int context_trigger_get_rule_by_id	(	int	rule_id,
		context_trigger_rule_h *	rule
	)

Gets a rule stored in the system by rule ID.

Since :: 2.4

Remarks:: The rule must be released using context_trigger_rule_destroy().

Parameters:

[in]	rule_id	The ID of the rule to be retrieved
[out]	rule	The rule retrieved

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_RULE_NOT_EXIST	Rule does not exist

int context_trigger_remove_rule ( int rule_id )

Removes a rule.

This removes the rule designated by the rule_id, which is owned by the application.

Since :: 2.4

Remarks:: If the rule has been activated, it should be disabled through context_trigger_disable_rule() in advance.

Parameters:

[in] rule_id The ID of the rule to be removed

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_RULE_ENABLED	Rule is enabled already
CONTEXT_TRIGGER_ERROR_RULE_NOT_EXIST	Rule does not exist

See also:: context_trigger_add_rule()

int context_trigger_rule_add_entry	(	context_trigger_rule_h	rule,
		context_trigger_rule_entry_h	entry
	)

Adds an event or a condition to a rule.

Since :: 2.4

Parameters:

[in]	rule	The rule
[in]	entry	The event or condition entry to be added to the rule

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

int context_trigger_rule_condition_create	(	context_trigger_condition_e	condition_item,
		context_trigger_logical_type_e	logical_type,
		context_trigger_rule_entry_h *	entry
	)

Creates a condition entry.

A condition of a contextual condition item is created.

Since :: 2.4

Remarks:: Regarding the condition_item, the application may require one of the following privileges:
http://tizen.org/privilege/network.get
http://tizen.org/privilege/telephony
http://tizen.org/privilege/apphistory.read
http://tizen.org/privilege/callhistory.read
http://tizen.org/privilege/mediahistory.read
If the application does not have necessary privilege, when registering the corresponding rule, context_trigger_add_rule() will return CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED. See context_trigger_condition_e to find the corresponding privilege of each condition item.
The entry must be released using context_trigger_rule_entry_destroy().

Parameters:

[in]	condition_item	The contextual condition item
[in]	logical_type	The logical operator
[out]	entry	The condition entry to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Memory allocation failed
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported condition contained

See also:: context_trigger_rule_entry_destroy()

int context_trigger_rule_condition_is_supported	(	context_trigger_condition_e	condition_item,
		bool *	supported
	)

Checks whether a contextual condition is supported in the current device.

Since :: 2.4

Parameters:

[in]	condition_item	The contextual condition item
[out]	supported	If supported, `true`; Otherwise, `false`

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed

int context_trigger_rule_create	(	context_trigger_logical_type_e	logical_type,
		context_trigger_rule_h *	rule
	)

Creates an empty rule.

An empty rule container is created. When using this, a logical operator, one of context_trigger_logical_type_e, needs to be designated.
In case of CONTEXT_TRIGGER_LOGICAL_CONJUNCTION, the rule can be satisfied only if all conditions are true. Otherwise, in case of CONTEXT_TRIGGER_LOGICAL_DISJUNCTION, the rule can be satisfied if at least one is true.

Since :: 2.4

Remarks:: The rule must be released using context_trigger_rule_destroy().

Parameters:

[in]	logical_type	The logical operator
[out]	rule	The rule handle to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Memory allocation failed

See also:: context_trigger_rule_destroy()

int context_trigger_rule_custom_condition_create	(	const char *	condition_item,
		const char *	provider,
		context_trigger_logical_type_e	logical_type,
		context_trigger_rule_entry_h *	entry
	)

Creates a condition entry with custom condition, instead of predefined condition item context_trigger_condition_e.

A condition of a custom contextual condition item, which is registered and will be provided by provider application/system, is created.

Since :: 3.0

Remarks:: The entry must be released using context_trigger_rule_entry_destroy().

Parameters:

[in]	condition_item	The custom contextual condition item
[in]	provider	The id of the package which provides the condition item
[in]	logical_type	The logical operator
[out]	entry	The condition entry to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Memory allocation failed
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported condition contained

See also:: context_trigger_rule_condition_create(); context_trigger_rule_entry_destroy()

int context_trigger_rule_custom_event_create	(	const char *	event_item,
		const char *	provider,
		context_trigger_logical_type_e	logical_type,
		context_trigger_rule_entry_h *	entry
	)

Creates an event entry with custom event, instead of predefined event item context_trigger_event_e.

An event of a custom contextual event item, which is registered and will be provided by an application/system, is created.

Since :: 3.0

Remarks:: The entry must be released using context_trigger_rule_entry_destroy().

Parameters:

[in]	event_item	The custom contextual event item
[in]	provider	The id of the package which provides the event item
[in]	logical_type	The logical operator
[out]	entry	The event entry to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Memory allocation failed
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event contained

See also:: context_trigger_rule_event_create(); context_trigger_rule_entry_destroy()

int context_trigger_rule_destroy ( context_trigger_rule_h rule )

Releases the resources occupied by a rule handle.

Since :: 2.4

Parameters:

[in] rule The rule handle to be released

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: context_trigger_rule_create()

See also:: context_trigger_get_rule_by_id()

int context_trigger_rule_entry_add_comparison	(	context_trigger_rule_entry_h	entry,
		const char *	key,
		const char *	comp_operator,
		const char *	event_data_key
	)

Adds a comparison between an attribute of a condition and an attribute extracted from the event.

The key needs to be registered in advance, via context_trigger_rule_entry_add_key().

Since :: 2.4

Parameters:

[in]	entry	The condition entry
[in]	key	The attribute key of the condition, which will be used as the left operand
[in]	comp_operator	The comparison operator
[in]	event_data_key	The event data key of which the corresponding data value will be used as the right operand

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_NO_DATA	The key was not added in the entry
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

Precondition:: context_trigger_rule_entry_add_key()

See also:: context_trigger_rule_entry_add_comparison_int(); context_trigger_rule_entry_add_comparison_string()

int context_trigger_rule_entry_add_comparison_int	(	context_trigger_rule_entry_h	entry,
		const char *	key,
		const char *	comp_operator,
		int	value
	)

Adds a comparison between an attribute key and an integer.

The key needs to be registered in advance, via context_trigger_rule_entry_add_key(). As the comparison operator, one of the following operators is allowed: CONTEXT_TRIGGER_EQUAL_TO, CONTEXT_TRIGGER_NOT_EQUAL_TO, CONTEXT_TRIGGER_LESS_THAN, CONTEXT_TRIGGER_GREATER_THAN, CONTEXT_TRIGGER_LESS_THAN_OR_EQUAL_TO and CONTEXT_TRIGGER_GREATER_THAN_OR_EQUAL_TO.

Since :: 2.4

Parameters:

[in]	entry	The event or condition entry
[in]	key	The attribute key, which will be used as the left operand
[in]	comp_operator	The comparison operator
[in]	value	The right operand value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_NO_DATA	The key was not added in the entry
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

Precondition:: context_trigger_rule_entry_add_key()

See also:: context_trigger_rule_entry_add_comparison(); context_trigger_rule_entry_add_comparison_string()

int context_trigger_rule_entry_add_comparison_string	(	context_trigger_rule_entry_h	entry,
		const char *	key,
		const char *	comp_operator,
		const char *	value
	)

Adds a comparison between an attribute key and a string.

The key needs to be registered in advance, via context_trigger_rule_entry_add_key(). As the comparison operator, one of the following operators is allowed: CONTEXT_TRIGGER_EQUAL_TO and CONTEXT_TRIGGER_NOT_EQUAL_TO.

Since :: 2.4

Parameters:

[in]	entry	The event or condition entry
[in]	key	The attribute key, which will be used as the left operand
[in]	comp_operator	The comparison operator
[in]	value	The right operand value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_NO_DATA	The key was not added in the entry
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

Precondition:: context_trigger_rule_entry_add_key()

See also:: context_trigger_rule_entry_add_comparison(); context_trigger_rule_entry_add_comparison_int()

int context_trigger_rule_entry_add_key	(	context_trigger_rule_entry_h	entry,
		context_trigger_logical_type_e	logical_type,
		const char *	key
	)

Adds an attribute key to an entry.

The key will be used as the left operand of comparisons. See the programming guide to find available attribute keys for each event/condition item.

Since :: 2.4

Parameters:

[in]	entry	The event or condition entry
[in]	logical_type	The logical operator
[in]	key	The attribute key

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

Postcondition:: context_trigger_rule_entry_add_comparison(); context_trigger_rule_entry_add_comparison_int(); context_trigger_rule_entry_add_comparison_string()

int context_trigger_rule_entry_add_option	(	context_trigger_rule_entry_h	entry,
		const char *	option_key,
		const char *	event_data_key
	)

Sets an option to a condition entry, which references an attribute that will be extracted from the event.

See the programming guide to find available option keys for each condition item.

Since :: 2.4

Parameters:

[in]	entry	The condition entry
[in]	option_key	The option key
[in]	event_data_key	The event data key of which the corresponding data value will be used as the option parameter

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

See also:: context_trigger_rule_entry_add_option_int(); context_trigger_rule_entry_add_option_string()

int context_trigger_rule_entry_add_option_int	(	context_trigger_rule_entry_h	entry,
		const char *	option_key,
		int	value
	)

Sets an integer type option to an event or condition entry.

See the programming guide to find available option keys for each event/condition item.

Since :: 2.4

Parameters:

[in]	entry	The event or condition entry
[in]	option_key	The option key
[in]	value	The option value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

See also:: context_trigger_rule_entry_add_option(); context_trigger_rule_entry_add_option_string()

int context_trigger_rule_entry_add_option_string	(	context_trigger_rule_entry_h	entry,
		const char *	option_key,
		const char *	value
	)

Sets a string type option to an event or condition entry.

See the programming guide to find available option keys for each event/condition item.

Since :: 2.4

Parameters:

[in]	entry	The event or condition entry
[in]	option_key	The option key
[in]	value	The option value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

See also:: context_trigger_rule_entry_add_option(); context_trigger_rule_entry_add_option_int()

int context_trigger_rule_entry_destroy ( context_trigger_rule_entry_h entry )

Releases the resource occupied by an entry.

Since :: 2.4

Parameters:

[in] entry The event or condition entry

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: context_trigger_rule_event_create(); context_trigger_rule_condition_create()

int context_trigger_rule_event_create	(	context_trigger_event_e	event_item,
		context_trigger_logical_type_e	logical_type,
		context_trigger_rule_entry_h *	entry
	)

Creates an event entry.

An event of a contextual event item, which will be monitored by the system, is created.

Since :: 2.4

Remarks:: Regarding the event_item, the application may require one of the following privileges:
http://tizen.org/privilege/alarm.set
http://tizen.org/privilege/network.get
http://tizen.org/privilege/telephony
http://tizen.org/privilege/message.read
http://tizen.org/privilege/contact.read
http://tizen.org/privilege/location
If the application does not have necessary privilege, when registering the corresponding rule, context_trigger_add_rule() will return CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED. See context_trigger_event_e to find the corresponding privilege of each event item.
The entry must be released using context_trigger_rule_entry_destroy().

Parameters:

[in]	event_item	The contextual event item
[in]	logical_type	The logical operator
[out]	entry	The event entry to be initialized

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Memory allocation failed
CONTEXT_TRIGGER_ERROR_NOT_SUPPORTED	Unsupported event contained

See also:: context_trigger_rule_entry_destroy()

int context_trigger_rule_event_is_supported	(	context_trigger_event_e	event_item,
		bool *	supported
	)

Checks whether a contextual event is supported in the current device.

Since :: 2.4

Parameters:

[in]	event_item	The contextual event item
[out]	supported	If supported, `true`; Otherwise, `false`

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed

int context_trigger_rule_get_description	(	context_trigger_rule_h	rule,
		char **	description
	)

Gets the description of a rule.

Since :: 2.4

Remarks:: The description must be released using free().

Parameters:

[in]	rule	The rule
[out]	description	The description of the rule

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed

See also:: context_trigger_rule_set_description()

int context_trigger_rule_set_action_app_control	(	context_trigger_rule_h	rule,
		app_control_h	app_control
	)

Sets a app launching request as the action of a rule.

Contextual Trigger accepts an App Control as the action of a rule, an application thus can be launched when the rule is satisfied.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appmanager.launch

Remarks:: In addition to the privilege http://tizen.org/privilege/appmanager.launch, if it is an App Control that makes a call to someone, the privilege http://tizen.org/privilege/call is also required.; The launch request of the service application is restricted. The function will return CONTEXT_TRIGGER_ERROR_INVALID_RULE, if the launch request is for the service application.

Parameters:

[in]	rule	The rule
[in]	app_control	The App Control, which will be used to launch an application

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED	Permission denied
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

int context_trigger_rule_set_action_notification	(	context_trigger_rule_h	rule,
		const char *	title,
		const char *	content,
		const char *	icon_path,
		app_control_h	app_control
	)

Sets a notification posting request as the action of a rule.

A basic notification can be posted when the rule is satisfied, which consists of the title, a content body text, an icon, and an App Control.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Remarks:: The app_control can be NULL. In that case, no application will be launched via the notification.

Parameters:

[in]	rule	The rule
[in]	title	The title text
[in]	content	The content body text
[in]	icon_path	The icon file path
[in]	app_control	The app control

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_PERMISSION_DENIED	Permission denied
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed
CONTEXT_TRIGGER_ERROR_INVALID_RULE	Invalid rule

int context_trigger_rule_set_description	(	context_trigger_rule_h	rule,
		const char *	description
	)

Sets the description of a rule.

Since :: 2.4

Parameters:

[in]	rule	The rule
[in]	description	The description to be set

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTEXT_TRIGGER_ERROR_NONE	Successful
CONTEXT_TRIGGER_ERROR_INVALID_PARAMETER	Invalid parameter
CONTEXT_TRIGGER_ERROR_OUT_OF_MEMORY	Out of memory
CONTEXT_TRIGGER_ERROR_OPERATION_FAILED	Operation failed

See also:: context_trigger_rule_get_description()

Required Header

Overview

Related Features

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation