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 long long timestamp;
 126         int accuracy;
 127         int count;
 128         double *values;
 129 } uas_sensor_info_t;
 130
 131 /* Active scan event types */
 132 typedef enum {
 133         UAS_ACTIVE_DEVICE_FOUND = 0x01,
 134         UAS_ACTIVE_SCAN_COMPLETED = 0x02
 135 } uas_active_scan_event_e;
 136
 137 /* Callback to be invoked on plug-in's state changes (Ready <-> Not Ready) */
 138 typedef void (*uas_state_changed_callback)(int state);
 139
 140 /*
 141  * Callback to be invoked on Presen/Absence detection is started/stopped by plug-in's
 142  * [Param] state - 0 = detection stopped, 1 = detection started.
 143  */
 144 typedef void (*uas_detection_state_changed_callback)(int state);
 145
 146 /*
 147  * Callback to be invoked on Presen/Absence detection status during detection operation
 148  * by plug-in's which do not support User identification.
 149  */
 150 typedef void (*uas_detection_status_changed_callback)(uas_detection_type_e type,
 151         void *sensor_info);
 152
 153 /*
 154  * Callback to be invoked on Presen/Absence detection by plug-in's which do
 155  * not support User identification.
 156  */
 157 typedef void (*uas_detection_callback)(uas_detection_type_e type, void *sensor_info);
 158
 159 /*
 160  * Callback to be invoked on Presen/Absence detection by plug-in's which
 161  * support User identification.
 162  *
 163  * [Param] device - Device for which Presence/Absence is detected.
 164  */
 165 typedef void (*uas_device_detection_callback)(uas_detection_type_e type,
 166         uas_device_info_t *device);
 167
 168 /*
 169  * Callback to be invoked in response to add_device() API
 170  *
 171  * [Param] status - Operation status Success/Fail
 172  * [Param] device - Device for which add_device() was invoked.
 173  */
 174 typedef void (*uas_device_added_callback)(int status, uas_device_info_t *device);
 175
 176 /*
 177  * Callback to be invoked in response to search_active_devices() API
 178  *
 179  * [Param] scan_event - UAS_ACTIVE_DEVICE_FOUND or, UAS_ACTIVE_SCAN_COMPLETED.
 180  * [Param] device - Found registerd device info if event is UAS_ACTIVE_DEVICE_FOUND
 181  * or, NULL if event is UAS_ACTIVE_SCAN_COMPLETED.
 182  */
 183 typedef void (*uas_device_active_scan_callback)(
 184                 uas_active_scan_event_e event, const uas_device_info_t *device);
 185
 186 /* UA plug-in callback structure */
 187 typedef struct {
 188         uas_state_changed_callback state_changed_cb; /**< 0:Not ready 1:Ready */
 189         uas_detection_state_changed_callback detection_state_cb; /**< 0:Stop 1:Start */
 190         uas_detection_status_changed_callback detection_status_cb; /**< 1: change with param */
 191         uas_detection_callback detected_cb; /**< For environmental sensors */
 192         uas_device_detection_callback device_detected_cb; /**< For connectivity sensors */
 193         uas_device_added_callback device_added_cb; /**< For connectivity sensors */
 194         uas_device_active_scan_callback active_scan_cb; /**< For connectivity sensors */
 195 } uas_callbacks_t;
 196
 197 typedef struct {
 198         /* [Sync API] To initialize senspor plug-in */
 199         int (*init)(const uas_callbacks_t* callbacks);
 200
 201         /* [Sync API] To deinitialize senspor plug-in */
 202         int (*deinit)(void);
 203
 204         /* [Sync API] To get plug-in's current state (READY/NOT_READY) */
 205         int (*get_state)(int *state);
 206
 207         /*
 208          * [Sync API] To get plug-in's detection capability to help check if
 209          * the plug-in supports user detection (Able to identify individual User's
 210          * Presence/Absence) or, it only support Presence/Absence detection of without
 211          * identifying users.
 212          */
 213         int (*get_capability)(uas_capability_e *capability);
 214
 215         /*
 216          * [Sync API] To send registered device list from user DB to plug-ins for
 217          * user/device detection. Called whenever device list changes (On device addition/removal).
 218          *
 219          * [Param] devices - List of registered devices relavant to the plug-in's operation.
 220          *      For example, for WIFI plugin, list contains only devices that were registered/added
 221          *      for WIFI detection.
 222          */
 223         int (*set_registered_devices)(int num_devices,
 224                         uas_device_info_t *devices);
 225
 226         /*
 227          * [Async API] To Add/register device to be used for User Presence/Absence detection.
 228          * uas_device_added_callback() will be called with result of the operation.
 229          *
 230          * [Param] device - Device to be added/registered.
 231          *
 232          */
 233         int (*add_device)(uas_device_info_t *device);
 234
 235         /*
 236          * [Sync API] To remove/unregister device from the list used for User Presence/Absence
 237          * detection.
 238          *
 239          * [Param] device - Device to be removed/unregistered.
 240          */
 241         int (*remove_device)(uas_device_info_t *device);
 242
 243         /* [Sync API] To start (User) Presence/Absence detection.
 244          *
 245          * [Param] type - What kind of event we should detectn.
 246          *      This type may use bit-wise operation for instance, if we would like to detect
 247          *  presence and absence simultaneously, we can set type like following:
 248          *  -> type = UAS_PRESENCE | UAS_ABSENCE.
 249          */
 250         int (*start_detection)(unsigned int detection_type);
 251
 252         /* [Sync API] To stop (User) Presence/Absence detection.
 253          *
 254          * [Param] type - What kind of event we should stop.
 255          *      This type may use bit-wise operation.
 256          */
 257         int (*stop_detection)(unsigned int detection_type);
 258
 259         /*
 260          * [Sync API] To enable/disable suspend mode in plug-in. If suspend mode is
 261          * enabled, subsequent call to start_detection() will trigger suspend mode operations
 262          * for device detection.
 263          * mode = 0 - Disable, mode = 1 - Enable
 264          */
 265         int (*set_low_power_mode)(int mode);
 266
 267         /*
 268          * [Sync API] To set detection window in plug-in.
 269          *
 270          * [Param] detection_window - Time in second for which User detection procedure is
 271          *      executed.
 272          */
 273         int (*set_detection_window)(unsigned int detection_window);
 274
 275         /*
 276          * [Sync API] To set detection threshold value in plug-in.
 277          *
 278          * [Param] presence_threshold - A threshold value for detecting presence [Usage - Optional]
 279          *      Ex:- In the case of a light plugin, this value is used as a threshold value for
 280          *      detecting presence.
 281          *
 282          * [Param] absence_threshold - Threshold value for detecting absence [Usage - Optional]
 283          *      Ex:- In the case of a light plugin, this value is used as a threshold value for
 284          *      detecting absence.
 285          */
 286         int (*set_detection_threshold)(int presence_threshold, int absence_threshold);
 287
 288         /*
 289          * [Async API] To search for currently active devices in proximity.
 290          *
 291          * [Param] detection_period - Time in second for which User detection procedure is
 292          * executed.
 293          *
 294          * Once detection_period is over, list of current active devices will be returned using
 295          * uas_active_devices_callback().
 296          *
 297          */
 298         int (*scan_active_devices)(int detection_period);
 299
 300         /*
 301          * [Async API] To cancel the ongoing active devices search.
 302          */
 303         int (*cancel_active_device_scan)(void);
 304
 305         /*
 306          * [Sync API] To set iBeacon adv data in plug-in.
 307          *
 308          * [Param] adv_len - The value of length of iBeacon adv data to add.
 309          *
 310          * [Param] iadv - iBeacon adv data to be add.
 311          */
 312         int (*add_ibeacon_adv)(unsigned int adv_len, const char *iadv);
 313 } uas_api_t;
 314
 315 typedef enum {
 316         UAS_PLUGIN_ID_BLE = 0,
 317         UAS_PLUGIN_ID_WIFI,
 318         UAS_PLUGIN_ID_LIGHT,
 319         UAS_PLUGIN_ID_MOTION,
 320         UAS_PLUGIN_ID_MAX
 321 } uas_plugin_id_e;
 322
 323 typedef struct {
 324         /** Identifier of module */
 325         int id;
 326
 327         /** Name of this module */
 328         const char *name;
 329
 330         /** Author/owner/implementor of the module */
 331         const char *author;
 332
 333         /** Version of the module-specific plugin API */
 334         const char *version;
 335
 336         /** Modules init */
 337         int (*init)(uas_api_t **api);
 338
 339         /** Modules de-init */
 340         int (*deinit)(void);
 341 } uas_module_t;
 342
 343 #define UAS_MODULE_ADD(id, name, author, version, init, deinit) \
 344         uas_module_t uas_module = { id, name, author, version, init, deinit };
 345
 346 #ifdef __cplusplus
 347 }
 348 #endif
 349 #endif /* __UAM_PLUGIN_H__ */