doc/appfw_event_doc.h

   1 /*
   2  * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd All Rights Reserved
   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 #ifndef __TIZEN_APPFW_EVENT_DOC_H__
  19 #define __TIZEN_APPFW_EVENT_DOC_H__
  20
  21  /**
  22  * @ingroup CAPI_APPLICATION_MODULE
  23  * @defgroup CAPI_EVENT_MODULE Event
  24  * @brief The @ref CAPI_EVENT_MODULE API provides functions to serve publication and subscription of the event.
  25  * @section CAPI_EVENT_MODULE_HEADER Required Header
  26  *   \#include <app_event.h>
  27  * @section CAPI_EVENT_MODULE_OVERVIEW Overview
  28  * The @ref CAPI_EVENT_MODULE API provides functions to broadcast user-defined event.
  29  * - event_publish_app_event()
  30  * - event_publish_trusted_app_event()
  31  * If you want to send an event to trusted application, you can use event_publish_trusted_app_event() API.
  32  * Only applications which have same signature with sender application can receive the event.
  33  * The @ref CAPI_EVENT_MODULE API provides functions to add and remove the event handler for event subscription.
  34  * The event handler's function will be called when the interested event occurs.
  35  * Adding multiple event handlers to one event is possible.
  36  * There are two types of events:
  37  * - User-Event is user-defined event.
  38  * - System-Event is pre-defined platform event. See definitions for system event.
  39  * NOTE: You can't receive the system-event which is not supported on the target device, even if you register event handler for that event.
  40  * Some system-events require the privilege. (Refer to @ref CAPI_EVENT_MODULE_PRIVILEGED_SYSTEM_EVENT)
  41  * The type of event data is bundle type.
  42  * - For System-Event, see definitions for key and value of system event.
  43  *
  44  * @subsection CAPI_EVENT_MODULE_EVENT_FORMAT The name-format of User-Event
  45  * The format of the User-Event's name MUST be "event.{sender's appid}.{user-defined name}", unless the API calls using event_name will fail.
  46  * The {user-defined name} have some restrictions.
  47  * - Must have length of Min 1 byte and Max 127 bytes.
  48  * - Must only contain the characters("[A~Z][a~z][0~9]_") and not begin with a digit.
  49  * For example,
  50  *     "event.org.tizen.testapp.user_event_1".
  51  *
  52  * @subsection CAPI_EVENT_MODULE_LAUNCH_ON_EVENT Launch-On-Event (Service Application only)
  53  * Service application can be launched by event triggering.
  54  * For Launch-On-Event,
  55  * - The APP_CONTROL_OPERATION_LAUNCH_ON_EVENT must be defined in the manifest file.
  56  * - The URI name represents event name and the format is "event://{event name"}".
  57  *         For URI example,
  58  *             "event://tizen.system.event.battery_charger_status". (System-Event)
  59  * - The APP_CONTROL_OPERATION_LAUNCH_ON_EVENT can not be requested via app_control_send_launch_request().
  60  * How to know the triggered event after launch by event triggering.
  61  * - You can get the event name and data in the first call of app_control_cb, which is called after 'Created' of application states.
  62  *
  63  * @code
  64  * static void
  65  * app_control(app_control_h app_control, void *data)
  66  * {
  67  *     // Check "launch on event"
  68  *     int ret = 0;
  69  *     const char *event_uri = "event://tizen.system.event.battery_charger_status";
  70  *     char *operation = NULL;
  71  *     char *uri = NULL;
  72  *     char *event_value = NULL;
  73  *
  74  *     ret = app_control_get_operation(app_control, &operation);
  75  *     if (ret == APP_CONTROL_ERROR_NONE && operation &&
  76  *         strcmp(operation, APP_CONTROL_OPERATION_LAUNCH_ON_EVENT) == 0) {
  77  *         ret = app_control_get_uri(app_control, &uri);
  78  *         if (ret == APP_CONTROL_ERROR_NONE && uri) {
  79  *             if (strncmp(uri, event_uri, strlen(event_uri) + 1) == 0) {
  80  *                 ret = app_control_get_extra_data(app_control, "battery_charger_status", &event_value);
  81  *                 if (ret == APP_CONTROL_ERROR_NONE && event_value)
  82  *                     free(event_value);
  83  *             }
  84  *             free(uri);
  85  *         }
  86  *         free(operation);
  87  *     }
  88  * }
  89  * @endcode
  90  * - Use event_add_event_handler() API in the first called app_control_cb for further subscription of that event.
  91  * NOTE: Only some of System-Events support Launch-On-Event.
  92  * The System-Events and their Conditions which support Launch-On-Event are listed in the table below.
  93  * <table>
  94  * <tr>
  95  * <th>Name</th>
  96  * <th>Condition</th>
  97  * </tr>
  98  * <tr>
  99  * <td>SYSTEM_EVENT_BATTERY_CHARGER_STATUS</td>
 100  * <td>When Charger CONNECTED</td>
 101  * </tr>
 102  * <tr>
 103  * <td>SYSTEM_EVENT_USB_STATUS</td>
 104  * <td>When USB CONNECTED</td>
 105  * </tr>
 106  * <tr>
 107  * <td>SYSTEM_EVENT_EARJACK_STATUS</td>
 108  * <td>When Earjack CONNECTED</td>
 109  * </tr>
 110  * <tr>
 111  * <td>SYSTEM_EVENT_INCOMING_MSG</td>
 112  * <td>When MSG_TYPE & MSG_ID exist</td>
 113  * </tr>
 114  * </table>
 115  *
 116  * @subsection CAPI_EVENT_MODULE_PRIVILEGED_SYSTEM_EVENT Privileged System-Events
 117  * There are some system-events which need the privilege for normal operation.
 118  * You can know these privileged system-events from the 'privilege' comment of the definition of each system-event.
 119  * If you try to add event handler for these events without privilege, you will get EVENT_ERROR_PERMISSION_DENIED return when you use the API for adding event handler.
 120  * Also, if you declare app_control operation and URI in the manifest file for these events to enable 'Launch On Event' without privilege, there will be no real launch.
 121  * @subsection CAPI_EVENT_MODULE_SYSTEM_EVENT Supported System-Events.
 122  * The supported system-event's name, keys, and values of each event are listed in the table below.
 123  * <table>
 124  * <tr>
 125  * <th>Name</th>
 126  * <th>Key</th>
 127  * <th>Value</th>
 128  * </tr>
 129  * <tr>
 130  * <td>SYSTEM_EVENT_BATTERY_CHARGER_STATUS</td>
 131  * <td>EVENT_KEY_BATTERY_CHARGER_STATUS</td>
 132  * <td>EVENT_VAL_BATTERY_CHARGER_DISCONNECTED<br/>EVENT_VAL_BATTERY_CHARGER_CONNECTED<br/>EVENT_VAL_BATTERY_CHARGER_CHARGING<br/>EVENT_VAL_BATTERY_CHARGER_DISCHARGING</td>
 133  * </tr>
 134  * <tr>
 135  * <td>SYSTEM_EVENT_BATTERY_LEVEL_STATUS</td>
 136  * <td>EVENT_KEY_BATTERY_LEVEL_STATUS</td>
 137  * <td>EVENT_VAL_BATTERY_LEVEL_EMPTY<br/>EVENT_VAL_BATTERY_LEVEL_CRITICAL<br/>EVENT_VAL_BATTERY_LEVEL_LOW<br/>EVENT_VAL_BATTERY_LEVEL_HIGH<br/>EVENT_VAL_BATTERY_LEVEL_FULL</td>
 138  * </tr>
 139  * <tr>
 140  * <td>SYSTEM_EVENT_USB_STATUS</td>
 141  * <td>EVENT_KEY_USB_STATUS</td>
 142  * <td>EVENT_VAL_USB_DISCONNECTED<br/>EVENT_VAL_USB_CONNECTED<br/>EVENT_VAL_USB_AVAILABLE</td>
 143  * </tr>
 144  * <tr>
 145  * <td>SYSTEM_EVENT_EARJACK_STATUS</td>
 146  * <td>EVENT_KEY_EARJACK_STATUS</td>
 147  * <td>EVENT_VAL_EARJACK_DISCONNECTED<br/>EVENT_VAL_EARJACK_CONNECTED</td>
 148  * </tr>
 149  * <tr>
 150  * <td>SYSTEM_EVENT_DISPLAY_STATE</td>
 151  * <td>EVENT_KEY_DISPLAY_STATE</td>
 152  * <td>EVENT_VAL_DISPLAY_NORMAL<br/>EVENT_VAL_DISPLAY_DIM<br/>EVENT_VAL_DISPLAY_OFF</td>
 153  * </tr>
 154  * <tr>
 155  * <td>SYSTEM_EVENT_BOOT_COMPLETED</td>
 156  * <td>N/A</td>
 157  * <td>N/A</td>
 158  * </tr>
 159  * <tr>
 160  * <td>SYSTEM_EVENT_SYSTEM_SHUTDOWN</td>
 161  * <td>N/A</td>
 162  * <td>N/A</td>
 163  * </tr>
 164  * <tr>
 165  * <td>SYSTEM_EVENT_LOW_MEMORY</td>
 166  * <td>EVENT_KEY_LOW_MEMORY</td>
 167  * <td>EVENT_VAL_MEMORY_NORMAL<br/>EVENT_VAL_MEMORY_SOFT_WARNING<br/>EVENT_VAL_MEMORY_HARD_WARNING</td>
 168  * </tr>
 169  * <tr>
 170  * <td>SYSTEM_EVENT_WIFI_STATE</td>
 171  * <td>EVENT_KEY_WIFI_STATE</td>
 172  * <td>EVENT_VAL_WIFI_OFF<br/>EVENT_VAL_WIFI_ON<br/>EVENT_VAL_WIFI_CONNECTED</td>
 173  * </tr>
 174  * <tr>
 175  * <td rowspan="3">SYSTEM_EVENT_BT_STATE</td>
 176  * <td>EVENT_KEY_BT_STATE</td>
 177  * <td>EVENT_VAL_BT_OFF<br/>EVENT_VAL_BT_ON</td>
 178  * </tr>
 179  * <tr>
 180  * <td>EVENT_KEY_BT_LE_STATE</td>
 181  * <td>EVENT_VAL_BT_LE_OFF<br/>EVENT_VAL_BT_LE_ON</td>
 182  * </tr>
 183  * <tr>
 184  * <td>EVENT_KEY_BT_TRANSFERING_STATE</td>
 185  * <td>EVENT_VAL_BT_NON_TRANSFERING<br/>EVENT_VAL_BT_TRANSFERING</td>
 186  * </tr>
 187  * <tr>
 188  * <td>SYSTEM_EVENT_LOCATION_ENABLE_STATE</td>
 189  * <td>EVENT_KEY_LOCATION_ENABLE_STATE</td>
 190  * <td>EVENT_VAL_LOCATION_DISABLED<br/>EVENT_VAL_LOCATION_ENABLED</td>
 191  * </tr>
 192  * <tr>
 193  * <td>SYSTEM_EVENT_GPS_ENABLE_STATE</td>
 194  * <td>EVENT_KEY_GPS_ENABLE_STATE</td>
 195  * <td>EVENT_VAL_GPS_DISABLED<br/>EVENT_VAL_GPS_ENABLED</td>
 196  * </tr>
 197  * <tr>
 198  * <td>SYSTEM_EVENT_NPS_ENABLE_STATE</td>
 199  * <td>EVENT_KEY_NPS_ENABLE_STATE</td>
 200  * <td>EVENT_VAL_NPS_DISABLED<br/>EVENT_VAL_NPS_ENABLED</td>
 201  * </tr>
 202  * <tr>
 203  * <td rowspan="2">SYSTEM_EVENT_INCOMING_MSG</td>
 204  * <td>EVENT_KEY_MSG_TYPE</td>
 205  * <td>EVENT_VAL_SMS<br/>EVENT_VAL_PUSH<br/>EVENT_VAL_CB</td>
 206  * </tr>
 207  * <tr>
 208  * <td>EVENT_KEY_MSG_ID</td>
 209  * <td>string of unsigned int type value.</td>
 210  * </tr>
 211  * <tr>
 212  * <td>SYSTEM_EVENT_TIME_CHANGED</td>
 213  * <td>N/A</td>
 214  * <td>N/A</td>
 215  * </tr>
 216  * <tr>
 217  * <td>SYSTEM_EVENT_TIME_ZONE</td>
 218  * <td>EVENT_KEY_TIME_ZONE</td>
 219  * <td>The value of this key is timezone value of tz database, for example,<br/> "Asia/Seoul", "America/New_York",<br/>. Refer to the Time Zone Database of IANA.</td>
 220  * </tr>
 221  * <tr>
 222  * <td>SYSTEM_EVENT_HOUR_FORMAT</td>
 223  * <td>EVENT_KEY_HOUR_FORMAT</td>
 224  * <td>EVENT_VAL_HOURFORMAT_12<br/>EVENT_VAL_HOURFORMAT_24</td>
 225  * </tr>
 226  * <tr>
 227  * <td>SYSTEM_EVENT_LANGUAGE_SET</td>
 228  * <td>EVENT_KEY_LANGUAGE_SET</td>
 229  * <td>The value of this key is full name of locale, for example,<br/> "ko_KR.UTF8" : in case of Korean language<br/> "en_US.UTF8" : in case of USA language,<br/>. Refer to linux locale info.</td>
 230  * </tr>
 231  * <tr>
 232  * <td>SYSTEM_EVENT_REGION_FORMAT</td>
 233  * <td>EVENT_KEY_REGION_FORMAT</td>
 234  * <td>The value of this key is full name of locale, for example,<br/> "ko_KR.UTF8" : in case of Korean region format<br/> "en_US.UTF8" : in case of USA region format,<br/>. Refer to linux locale info.</td>
 235  * </tr>
 236  * <tr>
 237  * <td>SYSTEM_EVENT_SILENT_MODE</td>
 238  * <td>EVENT_KEY_SILENT_MODE</td>
 239  * <td>EVENT_VAL_SILENTMODE_ON<br/>EVENT_VAL_SILENTMODE_OFF</td>
 240  * </tr>
 241  * <tr>
 242  * <td>SYSTEM_EVENT_VIBRATION_STATE</td>
 243  * <td>EVENT_KEY_VIBRATION_STATE</td>
 244  * <td>EVENT_VAL_VIBRATION_ON<br/>EVENT_VAL_VIBRATION_OFF</td>
 245  * </tr>
 246  * <tr>
 247  * <td>SYSTEM_EVENT_SCREEN_AUTOROTATE_STATE</td>
 248  * <td>EVENT_KEY_SCREEN_AUTOROTATE_STATE</td>
 249  * <td>EVENT_VAL_SCREEN_AUTOROTATE_ON<br/>EVENT_VAL_SCREEN_AUTOROTATE_OFF</td>
 250  * </tr>
 251  * <tr>
 252  * <td>SYSTEM_EVENT_MOBILE_DATA_STATE</td>
 253  * <td>EVENT_KEY_MOBILE_DATA_STATE</td>
 254  * <td>EVENT_VAL_MOBILE_DATA_OFF<br/>EVENT_VAL_MOBILE_DATA_ON</td>
 255  * </tr>
 256  * <tr>
 257  * <td>SYSTEM_EVENT_DATA_ROAMING_STATE</td>
 258  * <td>EVENT_KEY_DATA_ROAMING_STATE</td>
 259  * <td>EVENT_VAL_DATA_ROAMING_OFF<br/>EVENT_VAL_DATA_ROAMING_ON</td>
 260  * </tr>
 261  * <tr>
 262  * <td>SYSTEM_EVENT_FONT_SET</td>
 263  * <td>EVENT_KEY_FONT_SET</td>
 264  * <td>The value of this key is font name of string type by font-config.</td>
 265  * </tr>
 266  * <tr>
 267  * <td>SYSTEM_EVENT_NETWORK_STATUS</td>
 268  * <td>EVENT_KEY_NETWORK_STATUS</td>
 269  * <td>EVENT_VAL_NETWORK_DISCONNECTED<br/>EVENT_VAL_NETWORK_WIFI</br>EVENT_VAL_NETWORK_CELLULAR</br>EVENT_VAL_NETWORK_ETHERNET</br>EVENT_VAL_NETWORK_BT</br>EVENT_VAL_NETWORK_NET_PROXY</td>
 270  * </tr>
 271  * </table>
 272  */
 273
 274 #endif /* __TIZEN_APPFW_EVENT_DOC_H__ */
 275