1 /* 2 * Copyright (C) 2015-2018 Alibaba Group Holding Limited 3 */ 4 5 #ifndef LINKKIT_GATEWAY_EXPORT_H 6 #define LINKKIT_GATEWAY_EXPORT_H 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif /* __cplusplus */ 11 12 #if defined(__CC_ARM) 13 #define ssize_t int 14 #elif defined(__ICCARM__) 15 #define ssize_t int 16 #endif 17 18 /***************************Gateway Interface***************************/ 19 20 enum { 21 LINKKIT_EVENT_CLOUD_DISCONNECTED = 0, /* cloud disconnected */ 22 LINKKIT_EVENT_CLOUD_CONNECTED = 1, /* cloud connected */ 23 LINKKIT_EVENT_SUBDEV_DELETED = 2, /* subdev deleted */ 24 LINKKIT_EVENT_SUBDEV_PERMITED = 3, /* subdev permit join */ 25 LINKKIT_EVENT_SUBDEV_SETUP = 4, /* subdev install */ 26 }; 27 28 /* 29 * option | default | minimum | maximum 30 *--------------------------------|---------|---------|--------- 31 * LINKKIT_OPT_MAX_MSG_SIZE | 20480 | 512 | 51200 32 * LINKKIT_OPT_MAX_MSG_QUEUE_SIZE | 16 | 2 | 32 33 * LINKKIT_OPT_THREAD_POOL_SIZE | 4 | 1 | 16 34 * LINKKIT_OPT_THREAD_STACK_SIZE | 8192 | 1024 | 8388608 35 * LINKKIT_OPT_LOG_LEVEL | 3 | 0 | 5 36 */ 37 38 enum { 39 LINKKIT_OPT_MAX_MSG_SIZE = 1, 40 LINKKIT_OPT_MAX_MSG_QUEUE_SIZE = 2, 41 LINKKIT_OPT_THREAD_POOL_SIZE = 3, 42 LINKKIT_OPT_THREAD_STACK_SIZE = 4, 43 LINKKIT_OPT_PROPERTY_POST_REPLY = 5, /* data type: int */ 44 LINKKIT_OPT_EVENT_POST_REPLY = 6, /* data type: int */ 45 LINKKIT_OPT_PROPERTY_SET_REPLY = 7 /* data type: int */ 46 }; 47 48 typedef struct { 49 int event_type; /* see LINKKIT_EVENT_XXX for more details */ 50 51 union { 52 struct { 53 char *productKey; 54 char *deviceName; 55 } subdev_deleted; 56 57 struct { 58 char *productKey; 59 int timeoutSec; 60 } subdev_permited; 61 62 struct { 63 char * 64 subdevList; /* json 65 format:[{"productKey":"","deviceName":""},...] */ 66 } subdev_install; 67 } event_data; 68 } linkkit_event_t; 69 70 typedef struct linkkit_params_s { 71 int maxMsgSize; /* max message size */ 72 int maxMsgQueueSize; /* max message queue size */ 73 74 int threadPoolSize; /* number threads in pool */ 75 int threadStackSize; /* default thread stack size */ 76 77 int (*event_cb)(linkkit_event_t *ev, void *ctx); 78 79 /* user private data */ 80 void *ctx; 81 } linkkit_params_t; 82 83 /** 84 * @brief get default initialize parameters 85 * 86 * @return linkkit default parameters. 87 */ 88 linkkit_params_t *linkkit_gateway_get_default_params(void); 89 90 /** 91 * @brief set option in paremeters 92 * 93 * @param params, linkkit initialize parameters, return from 94 * linkkit_gateway_get_default_params(). 95 * @param option, see LINKKIT_OPT_XXX for more detail. 96 * @param value, value of option. 97 * @param value_len, value length. 98 * 99 * @return 0 when success, -1 when fail. 100 */ 101 int linkkit_gateway_setopt(linkkit_params_t *params, int option, void *value, 102 int value_len); 103 104 /** 105 * @brief set event callback 106 * 107 * @param params, linkkit initialize parameters, return from 108 * linkkit_gateway_get_default_params(). 109 * @param event_cb, event callback. 110 * @param ctx, user private data. 111 * 112 * @return 0 when success, < 0 when fail. 113 */ 114 int linkkit_gateway_set_event_callback(linkkit_params_t *params, 115 int (*event_cb)(linkkit_event_t *ev, 116 void *ctx), 117 void *ctx); 118 119 /** 120 * @brief linkkit initialization. 121 * 122 * @param initParams, linkkit initialize parameters, see linkkit_params_t for 123 * more detail. 124 * 125 * @return 0 when success, < 0 when fail. 126 */ 127 int linkkit_gateway_init(linkkit_params_t *initParams); 128 129 /** 130 * @brief linkkit deinitialization. 131 * 132 * @return 0 when success, < 0 when fail. 133 */ 134 int linkkit_gateway_exit(void); 135 136 typedef struct { 137 int (*register_complete)(void *ctx); 138 /** 139 * @brief get property callback. 140 * 141 * @param in, properties to be get, in JSON array format, terminated by 142 * NULL. 143 * @param out, output buffer fill by user, in json format, terminated by 144 * NULL. 145 * @param out_len, out buffer length. 146 * @param ctx, user private data passed by linkkit_gateway_start() or 147 * linkkit_gateway_subdev_create() 148 * 149 * @return 0 when success, -1 when fail. 150 */ 151 int (*get_property)(char *in, char *out, int out_len, void *ctx); 152 153 /** 154 * @brief set property callback. 155 * 156 * @param in, properties to be set, in JSON object format, terminated by 157 * NULL. 158 * @param ctx, user private data passed by linkkit_gateway_start() or 159 * linkkit_gateway_subdev_create() 160 * 161 * @return 0 when success, -1 when fail. 162 */ 163 int (*set_property)(char *in, void *ctx); 164 165 /** 166 * @brief call service callback. 167 * 168 * @param identifier, service identifier, available services define in TSL 169 * file. 170 * @param in, service input data, in JSON object format, terminated by NULL. 171 * @param out, service output, this buffer will be filled by user, in json 172 * format, terminated by NULL. 173 * @param out_len, out buffer length. 174 * @param ctx, user private data passed by linkkit_gateway_start() or 175 * linkkit_gateway_subdev_create(). 176 * 177 * @return 0 when success, -1 when fail. 178 */ 179 int (*call_service)(char *identifier, char *in, char *out, int out_len, 180 void *ctx); 181 182 /** 183 * @brief raw data from cloud. 184 * 185 * @param in, input data from cloud. 186 * @param in_len, input data length. 187 * @param out, output data to cloud, allocated by linkkit fill by user, no 188 * need to be free. 189 * @param out_len, out buffer length. 190 * @param ctx, user private data passed by linkkit_gateway_start() or 191 * linkkit_gateway_subdev_create(). 192 * 193 * @return output data size. < 0 when fail. 194 */ 195 int (*down_rawdata)(const void *in, int in_len, void *out, int out_len, 196 void *ctx); 197 198 /** 199 * @brief return data from cloud when calling 200 * linkkit_gateway_post_rawdata(). 201 * 202 * @param data, return raw data from cloud. 203 * @param len, data length. 204 * @param ctx, user private data passed by linkkit_gateway_start() or 205 * linkkit_gateway_subdev_create(). 206 * 207 * @return 0 when success, -1 when fail. 208 */ 209 int (*post_rawdata_reply)(const void *data, int len, void *ctx); 210 } linkkit_cbs_t; 211 212 /** 213 * @brief start linkkit gateway routines and install callback funstions. 214 * 215 * @param cbs, callback function struct to be installed. 216 * @param ctx, user context pointer. 217 * 218 * @return device id, 0 > when success, < 0 when fail. 219 */ 220 int linkkit_gateway_start(linkkit_cbs_t *cbs, void *ctx); 221 222 /** 223 * @brief stop linkkit gateway. 224 225 * @param devid, device id return from linkkit_gateway_start(). 226 * 227 * @return 0 when success, -1 when fail. 228 */ 229 int linkkit_gateway_stop(int devid); 230 231 /** 232 * @brief register subdev to gateway. 233 234 * @param productKey, subdev's product key. 235 * @param deviceName, subdev's device name. 236 * @param deviceSecret, subdev's device secret. 237 * 238 * @return 0 when success, -1 when fail. 239 */ 240 int linkkit_gateway_subdev_register(char *productKey, char *deviceName, 241 char *deviceSecret); 242 243 /** 244 * @brief deregister subdev from gateway. 245 246 * @param productKey, subdev's product key. 247 * @param deviceName, subdev's device name. 248 * 249 * @return 0 when success, -1 when fail. 250 */ 251 int linkkit_gateway_subdev_unregister(char *productKey, char *deviceName); 252 253 /** 254 * @brief create subdev and install callback funstions. 255 * 256 * @param productKey, subdev's product key. 257 * @param deviceName, subdev's device name. 258 * @param cbs, callback function struct to be installed. 259 * @param ctx, user context pointer. 260 * 261 * @return device id, 0 > when success, < 0 when fail. 262 */ 263 int linkkit_gateway_subdev_create(char *productKey, char *deviceName, 264 linkkit_cbs_t *cbs, void *ctx); 265 266 /** 267 * @brief destroy subdev by device id. 268 269 * @param devid, device id return from linkkit_gateway_subdev_create(). 270 * 271 * @return 0 when success, -1 when fail. 272 */ 273 int linkkit_gateway_subdev_destroy(int devid); 274 275 /** 276 * @brief make subdev accessible from cloud. 277 278 * @param devid, device id return from linkkit_gateway_subdev_create(). 279 * 280 * @return 0 when success, -1 when fail. 281 */ 282 int linkkit_gateway_subdev_login(int devid); 283 284 /** 285 * @brief make subdev inaccessible on cloud. 286 287 * @param devid, device id return from linkkit_gateway_subdev_create(). 288 * 289 * @return 0 when success, -1 when fail. 290 */ 291 int linkkit_gateway_subdev_logout(int devid); 292 293 enum { 294 LINKKIT_STATE_ENABLED = 0, /* device is enabled by cloud */ 295 LINKKIT_STATE_DISABLED, /* device is disabled by cloud */ 296 LINKKIT_STATE_REMOVED, /* device is deleted by cloud */ 297 }; 298 299 typedef struct { 300 char *productKey; /* device's product key */ 301 char *deviceName; /* device's device name */ 302 303 int devtype; /* Device Type: 0 - gateway, 1 - subdev */ 304 int login; /* Login State: 0 - logout, 1 - login */ 305 int state; /* Device State: see LINKKIT_STATE_xxx */ 306 int online; /* 0 - offline, 1 - online */ 307 } linkkit_devinfo_t; 308 309 /** 310 * @brief get device infomation specific by devid. 311 * 312 * @param devinfo, device information, see linkkit_devinfo_t for more detail. 313 * 314 * @return 0 when success, -1 when fail. 315 */ 316 int linkkit_gateway_get_devinfo(int devid, linkkit_devinfo_t *devinfo); 317 318 /** 319 * @brief post event to cloud. 320 * 321 * @param devid, device id return from linkkit_gateway_start() or 322 * linkkit_gateway_subdev_create(). 323 * @param identifier, event identifier, see tsl file for more detail. 324 * @param event, event data, in JSON format. 325 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 326 * 0, wait no response. 327 * 328 * @return 0 when success, -1 when fail. 329 */ 330 int linkkit_gateway_trigger_event_json_sync(int devid, char *identifier, 331 char *event, int timeout_ms); 332 333 /** 334 * @brief post event to cloud asynchronously. 335 * 336 * @param devid, device id return from linkkit_gateway_start() or 337 * linkkit_gateway_subdev_create(). 338 * @param identifier, event identifier, see tsl file for more detail. 339 * @param event, event data, in JSON format. 340 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 341 * 0, wait no response. 342 * @param func, callback function when success(retval > 0), timeout(retval = 0) 343 * or failed(retval < 0). 344 * @param ctx, user data passed to 'func'. 345 * 346 * @return 0 when success, -1 when fail. 347 */ 348 int linkkit_gateway_trigger_event_json(int devid, char *identifier, char *event, 349 int timeout_ms, 350 void (*func)(int retval, void *ctx), 351 void *ctx); 352 353 /** 354 * @brief post property to cloud. 355 * 356 * @param devid, device id return from linkkit_gateway_start() or 357 * linkkit_gateway_subdev_create(). 358 * @param property, property data, in JSON format. 359 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 360 * 0, wait no response. 361 * 362 * @return 0 when success, -1 when fail. 363 */ 364 int linkkit_gateway_post_property_json_sync(int devid, char *property, 365 int timeout_ms); 366 367 /** 368 * @brief post property to cloud asynchronously. 369 * 370 * @param devid, device id return from linkkit_gateway_start() or 371 * linkkit_gateway_subdev_create(). 372 * @param property, property data, in JSON format. 373 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 374 * 0, wait no response. 375 * @param func, callback function when success(retval > 0), timeout(retval = 0) 376 * or failed(retval < 0). 377 * @param ctx, user data passed to 'func'. 378 * 379 * @return 0 when success, -1 when fail. 380 */ 381 int linkkit_gateway_post_property_json(int devid, char *property, 382 int timeout_ms, 383 void (*func)(int retval, void *ctx), 384 void *ctx); 385 386 /** 387 * @brief post raw data to cloud. 388 * 389 * @param devid, device id return from linkkit_gateway_start() or 390 * linkkit_gateway_subdev_create(). 391 * @param data, raw data buffer pointer. 392 * @param len, raw data length. 393 * 394 * @return 0 when success, -1 when fail. 395 */ 396 int linkkit_gateway_post_rawdata(int devid, void *data, int len); 397 398 typedef enum { 399 LINKKIT_OTA_EVENT_NEW_VERSION_DETECTED = 1, 400 } linkkit_ota_event_t; 401 402 typedef enum { 403 service_fota_callback_type_new_version_detected = 10, 404 405 service_fota_callback_type_number, 406 } service_fota_callback_type_t; 407 408 typedef void (*handle_service_fota_callback_fp_t)( 409 service_fota_callback_type_t callback_type, const char *version); 410 411 /** 412 * @brief this function used to register callback for firmware ota. 413 * 414 * @param callback_fp, user callback which register to fota. (NULL for 415 * unregister) 416 * 417 * @return 0 when success, -1 when fail. 418 */ 419 int linkkit_gateway_fota_init(handle_service_fota_callback_fp_t callback_fp); 420 421 /** 422 * @brief this function used to execute fota process. 423 * 424 * @param data_buf, data buf that used to do ota. ota service will use this 425 * buffer to download bin. 426 * @param data_buf_length, data buf length that used to do ota. 427 * 428 * @return 0 when success, -1 when fail. 429 */ 430 int linkkit_gateway_invoke_fota_service(void *data_buf, int data_buf_length); 431 432 typedef struct { 433 char *attrKey; /* the key of extend info. */ 434 char *attrValue; /* the value of extend info. */ 435 } linkkit_extinfo_t; 436 437 /** 438 * @brief post group of extend info to cloud 439 * 440 * @param devid, device id return from linkkit_gateway_start() or 441 * linkkit_gateway_subdev_create(). 442 * @param extinfos, group of extend info to be post. 443 * @param nb_extinfos, number of extend infos in extinfos. 444 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 445 * 0, wait no response. 446 * 447 * @return 0 when success, < 0 when fail. 448 */ 449 int linkkit_gateway_post_extinfos(int devid, linkkit_extinfo_t *extinfos, 450 int nb_extinfos, int timeout_ms); 451 452 /** 453 * @brief delete extend info specific by key 454 * 455 * @param devid, device id return from linkkit_gateway_start() or 456 * linkkit_gateway_subdev_create(). 457 * @param extinfos, group of extend info to be deleted, attrValue in 458 * linkkit_extinfo_t will be ignore. 459 * @param nb_extinfos, number of extend infos in extinfos. 460 * @param timeout_ms, transmission timeout, in milliseconds. when timeout_ms is 461 * 0, wait no response. 462 * 463 * @return 0 when success, < 0 when fail. 464 */ 465 int linkkit_gateway_delete_extinfos(int devid, linkkit_extinfo_t *extinfos, 466 int nb_extinfos, int timeout_ms); 467 468 /** 469 * @brief get number devices currently in gateway 470 * 471 * @return number devinfos. 472 */ 473 int linkkit_gateway_get_num_devices(void); 474 475 #ifdef __cplusplus 476 } 477 #endif /* __cplusplus */ 478 479 #endif /* LINKKIT_GATEWAY_EXPORT_H */ 480