ua-plugins/include/ua-plugin.h

   1 /*
   2  * Copyright (c) 2018 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 __UAM_PLUGIN_H__
  19 #define __UAM_PLUGIN_H__
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /* To be used in case user_id is not known */
  26 #define USER_ID_UNKNOWN_USER -1
  27
  28 /* UA Plugin states */
  29 typedef enum {
  30         UAS_STATE_NOT_READY = 0x00,
  31         UAS_STATE_READY
  32 } uas_state_e;
  33
  34 /* Operating System types */
  35 typedef enum {
  36         UAS_OS_TYPE_UNDEFINED = 0x00,
  37         UAS_OS_TYPE_TIZEN,
  38         UAS_OS_TYPE_ANDROID,
  39         UAS_OS_TYPE_IOS,
  40         UAS_OS_TYPE_INVALID
  41 } uas_os_type_e;
  42
  43 /* Supported technologies by device */
  44 typedef enum {
  45         UAS_TECH_TYPE_NONE = 0x00,
  46         UAS_TECH_TYPE_BT = 0x01,
  47         UAS_TECH_TYPE_BLE = 0x02,
  48         UAS_TECH_TYPE_WIFI = 0x04,
  49         UAS_TECH_TYPE_P2P = 0x08,
  50 } uas_tech_type_e;
  51
  52 /* Device Address types */
  53 typedef enum {
  54         UAS_ADDR_TYPE_BT = 0x01,
  55         UAS_ADDR_TYPE_BLE,
  56         UAS_ADDR_TYPE_WIFI,
  57         UAS_ADDR_TYPE_P2P,
  58         UAS_ADDR_TYPE_IPv4,
  59         UAS_ADDR_TYPE_IPv6,
  60         UAS_ADDR_TYPE_INVALID
  61 } uas_address_type_e;
  62
  63 /* UA plugin return status */
  64 #define FOREACH_STATUS(STATUS) \
  65         STATUS(UAS_STATUS_SUCCESS, 0x00) \
  66         STATUS(UAS_STATUS_FAIL, 0x01) \
  67         STATUS(UAS_STATUS_NOT_READY, 0x02) \
  68         STATUS(UAS_STATUS_NOMEM, 0x03) \
  69         STATUS(UAS_STATUS_BUSY, 0x04) \
  70         STATUS(UAS_STATUS_ALREADY_DONE, 0x05) \
  71         STATUS(UAS_STATUS_UNSUPPORTED, 0x06) \
  72
  73 #define GENERATE_STATUS_ENUM(ENUM, offset) ENUM = -offset,
  74 #define GENERATE_STATUS_STRING(STRING, offset) #STRING,
  75
  76 typedef enum {
  77         FOREACH_STATUS(GENERATE_STATUS_ENUM)
  78 } uas_status_e;
  79
  80 /*
  81  * Plugin capability :
  82  *      - User detection Not Supported,
  83  *      - User detection supported,
  84  */
  85 typedef enum {
  86         UAS_NOT_SUPPORT_USER,
  87         UAS_SUPPORT_USER
  88 } uas_capability_e;
  89
  90 /* Detection event types */
  91 typedef enum {
  92         UAS_PRESENCE = 0x01,
  93         UAS_ABSENCE = 0x02
  94 } uas_detection_type_e;
  95
  96 /* Device address information structure */
  97 typedef struct {
  98         uas_address_type_e type;
  99         char *address;
 100 } uas_address_info_t;
 101
 102 /* Device ble payload information structure */
 103 typedef struct {
 104         char service_id; /** Service Id */
 105         char device_icon; /** Device icon */
 106         char purpose; /** Purpose */
 107         char *duid; /** DUID */
 108         char *bt_mac; /** BT MAC Address */
 109 } uas_ble_payload_t;
 110
 111 /* Device information structure */
 112 typedef struct {
 113         int user_id;
 114         unsigned int supported_techs;
 115         char *device_id;
 116         int os;
 117         int num_addr;
 118         uas_address_info_t *addr_list;
 119         int discriminant; /**< Determines whether to judge PRESENCE/ABSENCE */
 120         uas_ble_payload_t *payload;
 121 } uas_device_info_t;
 122
 123 /* Sensor information structure */
 124 typedef struct {
 125         unsigned int status; /**< Sensor status */
 126         unsigned long long timestamp; /**< Timestamp */
 127         int accuracy; /**< Accuracy */
 128         int count; /**< How many sensor data are there */
 129         double *values; /**< Sensor data */
 130 } uas_sensor_info_t;
 131
 132 /* Active scan event types */
 133 typedef enum {
 134         UAS_ACTIVE_DEVICE_FOUND = 0x01,
 135         UAS_ACTIVE_SCAN_COMPLETED = 0x02
 136 } uas_active_scan_event_e;
 137
 138 /* Callback to be invoked on plug-in's state changes (Ready <-> Not Ready) */
 139 typedef void (*uas_state_changed_callback)(int state);
 140
 141 /*
 142  * Callback to be invoked on Presen/Absence detection is started/stopped by plug-in's
 143  * [Param] state - 0 = detection stopped, 1 = detection started.
 144  */
 145 typedef void (*uas_detection_state_changed_callback)(int state);
 146
 147 /*
 148  * Callback to be invoked on Presen/Absence detection status during detection operation
 149  * by plug-in's which do not support User identification.
 150  */
 151 typedef void (*uas_detection_status_changed_callback)(uas_detection_type_e type,
 152         void *sensor_info);
 153
 154 /*
 155  * Callback to be invoked on Presen/Absence detection by plug-in's which do
 156  * not support User identification.
 157  */
 158 typedef void (*uas_detection_callback)(uas_detection_type_e type, void *sensor_info);
 159
 160 /*
 161  * Callback to be invoked on Presen/Absence detection by plug-in's which
 162  * support User identification.
 163  *
 164  * [Param] device - Device for which Presence/Absence is detected.
 165  */
 166 typedef void (*uas_device_detection_callback)(uas_detection_type_e type,
 167         uas_device_info_t *device);
 168
 169 /*
 170  * Callback to be invoked in response to add_device() API
 171  *
 172  * [Param] status - Operation status Success/Fail
 173  * [Param] device - Device for which add_device() was invoked.
 174  */
 175 typedef void (*uas_device_added_callback)(int status, uas_device_info_t *device);
 176
 177 /*
 178  * Callback to be invoked in response to search_active_devices() API
 179  *
 180  * [Param] scan_event - UAS_ACTIVE_DEVICE_FOUND or, UAS_ACTIVE_SCAN_COMPLETED.
 181  * [Param] device - Found registerd device info if event is UAS_ACTIVE_DEVICE_FOUND
 182  * or, NULL if event is UAS_ACTIVE_SCAN_COMPLETED.
 183  */
 184 typedef void (*uas_device_active_scan_callback)(
 185                 uas_active_scan_event_e event, const uas_device_info_t *device);
 186
 187 /* UA plug-in callback structure */
 188 typedef struct {
 189         uas_state_changed_callback state_changed_cb; /**< 0:Not ready 1:Ready */
 190         uas_detection_state_changed_callback detection_state_cb; /**< 0:Stop 1:Start */
 191         uas_detection_status_changed_callback detection_status_cb; /**< 1: change with param */
 192         uas_detection_callback detected_cb; /**< For environmental sensors */
 193         uas_device_detection_callback device_detected_cb; /**< For connectivity sensors */
 194         uas_device_added_callback device_added_cb; /**< For connectivity sensors */
 195         uas_device_active_scan_callback active_scan_cb; /**< For connectivity sensors */
 196 } uas_callbacks_t;
 197
 198 typedef struct {
 199         /* [Sync API] To initialize senspor plug-in */
 200         int (*init)(const uas_callbacks_t* callbacks);
 201
 202         /* [Sync API] To deinitialize senspor plug-in */
 203         int (*deinit)(void);
 204
 205         /* [Sync API] To get plug-in's current state (READY/NOT_READY) */
 206         int (*get_state)(int *state);
 207
 208         /*
 209          * [Sync API] To get plug-in's detection capability to help check if
 210          * the plug-in supports user detection (Able to identify individual User's
 211          * Presence/Absence) or, it only support Presence/Absence detection of without
 212          * identifying users.
 213          */
 214         int (*get_capability)(uas_capability_e *capability);
 215
 216         /*
 217          * [Sync API] To send registered device list from user DB to plug-ins for
 218          * user/device detection. Called whenever device list changes (On device addition/removal).
 219          *
 220          * [Param] devices - List of registered devices relavant to the plug-in's operation.
 221          *      For example, for WIFI plugin, list contains only devices that were registered/added
 222          *      for WIFI detection.
 223          */
 224         int (*set_registered_devices)(int num_devices,
 225                         uas_device_info_t *devices);
 226
 227         /*
 228          * [Async API] To Add/register device to be used for User Presence/Absence detection.
 229          * uas_device_added_callback() will be called with result of the operation.
 230          *
 231          * [Param] device - Device to be added/registered.
 232          *
 233          */
 234         int (*add_device)(uas_device_info_t *device);
 235
 236         /*
 237          * [Sync API] To remove/unregister device from the list used for User Presence/Absence
 238          * detection.
 239          *
 240          * [Param] device - Device to be removed/unregistered.
 241          */
 242         int (*remove_device)(uas_device_info_t *device);
 243
 244         /* [Sync API] To start (User) Presence/Absence detection.
 245          *
 246          * [Param] type - What kind of event we should detectn.
 247          *      This type may use bit-wise operation for instance, if we would like to detect
 248          *  presence and absence simultaneously, we can set type like following:
 249          *  -> type = UAS_PRESENCE | UAS_ABSENCE.
 250          */
 251         int (*start_detection)(unsigned int detection_type);
 252
 253         /* [Sync API] To stop (User) Presence/Absence detection.
 254          *
 255          * [Param] type - What kind of event we should stop.
 256          *      This type may use bit-wise operation.
 257          */
 258         int (*stop_detection)(unsigned int detection_type);
 259
 260         /*
 261          * [Sync API] To enable/disable suspend mode in plug-in. If suspend mode is
 262          * enabled, subsequent call to start_detection() will trigger suspend mode operations
 263          * for device detection.
 264          * mode = 0 - Disable, mode = 1 - Enable
 265          */
 266         int (*set_low_power_mode)(int mode);
 267
 268         /*
 269          * [Sync API] To set detection window in plug-in.
 270          *
 271          * [Param] detection_window - Time in second for which User detection procedure is
 272          *      executed.
 273          */
 274         int (*set_detection_window)(unsigned int detection_window);
 275
 276         /*
 277          * [Sync API] To set detection threshold value in plug-in.
 278          *
 279          * [Param] presence_threshold - A threshold value for detecting presence [Usage - Optional]
 280          *      Ex:- In the case of a light plugin, this value is used as a threshold value for
 281          *      detecting presence.
 282          *
 283          * [Param] absence_threshold - Threshold value for detecting absence [Usage - Optional]
 284          *      Ex:- In the case of a light plugin, this value is used as a threshold value for
 285          *      detecting absence.
 286          */
 287         int (*set_detection_threshold)(int presence_threshold, int absence_threshold);
 288
 289         /*
 290          * [Async API] To search for currently active devices in proximity.
 291          *
 292          * [Param] detection_period - Time in second for which User detection procedure is
 293          * executed.
 294          *
 295          * Once detection_period is over, list of current active devices will be returned using
 296          * uas_active_devices_callback().
 297          *
 298          */
 299         int (*scan_active_devices)(int detection_period);
 300
 301         /*
 302          * [Async API] To cancel the ongoing active devices search.
 303          */
 304         int (*cancel_active_device_scan)(void);
 305
 306         /*
 307          * [Sync API] To set iBeacon adv data in plug-in.
 308          *
 309          * [Param] adv_len - The value of length of iBeacon adv data to add.
 310          *
 311          * [Param] iadv - iBeacon adv data to be add.
 312          */
 313         int (*add_ibeacon_adv)(unsigned int adv_len, const char *iadv);
 314 } uas_api_t;
 315
 316 typedef enum {
 317         UAS_PLUGIN_ID_BLE = 0,
 318         UAS_PLUGIN_ID_WIFI,
 319         UAS_PLUGIN_ID_LIGHT,
 320         UAS_PLUGIN_ID_MOTION,
 321         UAS_PLUGIN_ID_MAX
 322 } uas_plugin_id_e;
 323
 324 typedef struct {
 325         /** Identifier of module */
 326         int id;
 327
 328         /** Name of this module */
 329         const char *name;
 330
 331         /** Author/owner/implementor of the module */
 332         const char *author;
 333
 334         /** Version of the module-specific plugin API */
 335         const char *version;
 336
 337         /** Modules init */
 338         int (*init)(uas_api_t **api);
 339
 340         /** Modules de-init */
 341         int (*deinit)(void);
 342 } uas_module_t;
 343
 344 #define UAS_MODULE_ADD(id, name, author, version, init, deinit) \
 345         uas_module_t uas_module = { id, name, author, version, init, deinit };
 346
 347 #ifdef __cplusplus
 348 }
 349 #endif
 350 #endif /* __UAM_PLUGIN_H__ */