doc/context_trigger_doc.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @ingroup             CAPI_CONTEXT_FRAMEWORK
  19  * @defgroup    CAPI_CONTEXT_TRIGGER_MODULE Contextual Trigger
  20  *
  21  * @brief               The contextual trigger API provides a way to define rules,
  22  *                              each of which can trigger a specified action when the rule is satisfied.
  23  *
  24  * @section             CAPI_CONTEXT_TRIGGER_MODULE_HEADER Required Header
  25  *                              \#include <context_trigger.h>
  26  *
  27  * @section             CAPI_CONTEXT_TRIGGER_MODULE_OVERVIEW Overview
  28  *
  29  * The contextual trigger API provides a way to define trigger rules,
  30  * each of which launches an application or posts a notification if it is satisfied.
  31  *
  32  * To use this API, an application first needs to assemble a @em rule,
  33  * which consists of the following three components:
  34  *
  35  <ol>
  36         <li><b>An Event</b>:
  37                 The contextual trigger engine starts to verify if the rule is satisfied, when the event occurs.
  38                 As the name suggests, it is literally an event that can be recognized in the device,
  39                 e.g., changes of setting values or connections of peripherals.
  40                 See #context_trigger_event_e for all available event items.
  41         <li><b>A Set of Conditions</b>:
  42                 If the event occurs, the trigger engine checks whether the conditions are satisfied or not.
  43                 The application can choose the way of combining conditions, i.e., logical conjunction or disjunction.
  44                 In case of logical conjunction, for example, the set of conditions is @c true if and only if
  45                 all conditions are @c true.
  46                 If no condition is set, i.e., the set of conditions is empty, the trigger engine
  47                 considers the set is satisfied, regardless of the current context.
  48                 See #context_trigger_condition_e for all available condition items.
  49         <li><b>An Action</b>: If the conditions are satisfied, a designated action will be triggered.
  50                 The action can be an app launching request or a notification posting request.
  51  </ol>
  52  *
  53  * Note that, a rule only can be managed by the application that has registered the rule.
  54  *
  55  * If the rule is not required anymore, it can be disabled and removed from the engine.
  56  * Note that, rule activation, deactivation, and removals are only allowed to the
  57  * owner application, which has registered the rule to the trigger engine.
  58  * In the below example, the application queries its own rule IDs,
  59  * deactivates enabled rules, and removes all rules from the trigger engine.
  60  *
  61  * For more details, please see the programming guide and the tutorial.
  62  *
  63  *
  64  * @section CAPI_CONTEXT_TRIGGER_MODULE_FEATURE Related Features
  65  *
  66  * Some of the event and condition items in this API are related with one of the following features:@n
  67  * - http://tizen.org/feature/network.telephony
  68  * - http://tizen.org/feature/location.gps
  69  * - http://tizen.org/feature/network.bluetooth
  70  * - http://tizen.org/feature/network.wifi
  71  *
  72  * It is recommended to design feature related code in your application for reliability.@n
  73  * For your convenience, context_trigger_rule_event_is_supported() and context_trigger_rule_condition_is_supported()
  74  * are provided. Applications can use these functions to check the availability of a necessary event or condition,
  75  * before registering a rule, to be sure that the rule is valid in the current device.
  76  *
  77  * In general, you can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE,
  78  * thereby controlling the procedure of your application.
  79  * To ensure your application is only running on the device with specific features,
  80  * please define the features in your manifest file using the manifest editor in the SDK.
  81  * More details on featuring your application can be found from
  82  * <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
  83  */