网关API使用说明

更新时间：2018-07-04 14:11:45

结构体

linkkit_event_t

typedef struct {
    int event_type; /* see LINKKIT_EVENT_XXX for more details */

    union {
        struct {
            char *productKey;
            char *deviceName;
        } subdev_deleted;

        struct {
            char *productKey;
            int   timeoutSec;
        } subdev_permited;

        struct {
            char *subdevList;
        } subdev_setup;

        struct {
            char *productKey;
            char *deviceName;
        } reset_success;
    } event_data;
} linkkit_event_t;

linkkit_event_t用于表示网关SDK内部事件，包括以下成员：

• event_type：事件类型，支持的事件类型如下表所示：

• event_data：event_type指定的事件对应的事件数据。

linkkit_cbs_t

typedef struct {
    int (*get_property)(char *in, char *out, int out_len, void *ctx);
    int (*set_property)(char *in, void *ctx);
    int (*call_service)(char *identifier, char *in, char *out, int out_len, void *ctx);

    int (*down_rawdata)(const void *in, int in_len, void *out, int out_len, void *ctx);
    int (*post_rawdata_reply)(const void *data, int len, void *ctx);
} linkkit_cbs_t;

linkkit_cbs_t用于linkkit_gateway_start()和linkkit_gateway_subdev_create()，定义了设备支持的一组操作，包含以下回调函数：

• get_property: 云端用于获取设备或网关的各种属性，in为输入参数，为json数组，out为输出参数，是以'\0'结尾的json对象，out_len为out字符串的长度，out_len的大小与LINKKIT_OPT_MAX_MSG_SIZE指定的最大消息大小相同。ctx为用户私有数据。如果用户需要获取灯的WorkMode和Brightness两个属性，且WorkMode为1，Brightness为70%，则get_property的in参数为["WorkMode", "Brightness"]，out为：{ "WorkMode": 1, "Brightness": 70}

• set_property: 云端用于设置网关或子设备的各种属性，in为输入参数，为json对象，ctx为用户私有数据。如果用户想要设置的灯的WorkMode属性为2，Brightness属性为85，则in为{"WorkMode": 2,"Brightness": 85}

• call_service: 云端调用子设备服务，identifier为服务名称，in为服务的输入参数，为json对象，out为服务的输出参数，是以'\0'结尾的json对象，out_len为out字符串的长度，ctx为用户私有数据。如果云端想调用灯的SetLightSwitch这个服务，则identifier为SetLightSwitch，in参数为{"LightSwitch": 1}，out参数为{"Brightness":75}

• down_rawdata: 云端用于向IoT设备下发裸数据，in为云端下发数据，in_len为in的字节长度，out为网关SDK内部分配的存储空间，用于填充用户的返回数据，out_len为out的字节长度，ctx为用户私有数据，回调的返回值为out的实际长度；

• post_rawdata_reply: 云端返回用户调用linkkit_gateway_post_rawdata后的响应数据，data为数据，len为data的长度；

注意：linkkit_cbs_t中的down_rawdata和post_rawdata_reply两个回调功能暂不开放。

获取默认参数

linkkit_params_t *linkkit_gateway_get_default_params(void);

获取默认参数，在调用linkkit_gateway_init()时作为参数传入，用于初始化网关SDK。

修改默认参数

int linkkit_gateway_set_option(linkkit_params_t *params, int option, void *value, int value_len);

对linkkit_gateway_get_default_params()返回的默认参数进行修改，支持的option包括如下：

enum {
    LINKKIT_OPT_MAX_MSG_SIZE       = 1,
    LINKKIT_OPT_MAX_MSG_QUEUE_SIZE = 2,
    LINKKIT_OPT_THREAD_POOL_SIZE   = 3,
    LINKKIT_OPT_THREAD_STACK_SIZE  = 4,
    LINKKIT_OPT_LOG_LEVEL          = 5
};

option的值类型和取值范围如下表所示：

注册事件回调

int linkkit_gateway_set_event_callback(linkkit_params_t *params, int (*event_cb)(linkkit_event_t *ev, void *ctx), void *ctx);

该函数用于注册用户事件回调，包括以下参数：

• params：linkkit_gateway_get_default_params()返回的默认参数；

• event_cb：事件回调，linkkit内部事件会通过event_cb回调给用户；

• ctx：用户私有数据，在linkkit在调用event_cb时会传该event_cb；

event_cb包含以下参数：

• ev：事件结构体，详见linkkit_event_t；

• ctx：用户私有数据；

网关SDK初始化

int linkkit_gateway_init(linkkit_params_t *initParams);

用于分配和初始化linkkit的内部资源。

网关SDK反初始化

int linkkit_gateway_exit(void);

用于销毁和回收内部资源。在调用linkkit_gateway_exit()前，应该先销毁网关设备和所有子设备；

启动网关设备

int linkkit_gateway_start(linkkit_cbs_t *cbs, void *ctx);

用于创建网关设备，注册网关相关回调函数，同时启动linkkit服务，与云端建立。该函数有两个输入参数，cbs为设备操作相关的一组函数指针，ctx为用户私有数据。

linkkit_gateway_start()创建网关设备成功则返回大于0的设备id，创建失败则返回小于0的错误码。

停止网关设备

int linkkit_gateway_stop(int devid);

断开与云端的连接，停止网关SDK服务。

网关绑定子设备

int linkkit_gateway_subdev_register(char *productKey, char *deviceName, char *deviceSecret);

将productKey、deviceName和deviceSecret指定的子设备绑定到网关，将子设备添加到网关的拓扑中。

网关解绑子设备

int linkkit_gateway_subdev_unregister(char *productKey, char *deviceName);

解除网关与productKey、deviceName指定的子设备之间的绑定，删除网关与子设备的拓扑关系；

创建子设备

int linkkit_gateway_subdev_create(char *productKey, char *deviceName, linkkit_cbs_t *cbs, void *ctx);

创建子设备，注册子设备相关的回调和用户数据。linkkit_gateway_subdev_create()调用成功会返回子设备的devid（设备id），devid为大于0的整数，小于0为错误码。

删除子设备

int linkkit_gateway_subdev_destroy(int devid);

删除子设备，释放子设备相关的资源。

子设备login

int linkkit_gateway_subdev_login(int devid);

子设备登录，返回值等于0代表login成功，云端设备控制台会显示设备在线，小于0代表login失败。

子设备logout

int linkkit_gateway_subdev_logout(int devid);

子设备登出，等于0代表子设备logout成功，云端控制台显示设备离线，小于0代表logout失败。

事件上报

同步接口

int linkkit_gateway_trigger_event_json_sync(int devid, char *identifer, char *event, int timeout);

用于上报网关或子设备的事件到云端，包括以下参数：

• devid: 设备ID；

• identifer: 输入参数，事件标识，由TSL文档定义；

• event: 输入参数，待上报事件对应的数据，使用json格式表示，形如{"errorCode": 1}，以'\0'结尾；

• timeout：同步等待云端响应的超时时间，以毫秒为单位，为0则不等待云端响应；

异步接口

int linkkit_gateway_trigger_event_json(int devid, char *identifier, char *json, int timeout_ms, void (*func)(int retval, void *ctx), void *ctx);

用于上报网关或子设备的事件到云端，包括以下参数：

• devid: 设备ID；

• identifer: 输入参数，事件标识，由TSL文档定义；

• event: 输入参数，待上报事件对应的数据，使用json格式表示，形如{"errorCode": 1}，以'\0'结尾；

• timeout：同步等待云端响应的超时时间，以毫秒为单位，为0则不等待云端响应；

• cb：接口调用失败或成功时调用的回调函数，retval = 0表示超时，retval < 0表示云端响应错误，retval = 1表示成功；

• ctx：传递给cb的用户私有数据；

属性上报

同步接口

int linkkit_gateway_post_property_json_sync(int devid,char *property, int timeout);

用于网关或子设备主动上报属性到云端，该接口包括以下参数：

• devid: 设备ID；

• property: 输入参数，属性值，使用json格式表示，形如{"WorkMode": 1, "LightSwitch": 0}，以'\0'结尾；

• timeout：同步等待云端响应的超时时间，以毫秒为单位，为0则不等待云端响应。

异步接口

int linkkit_gateway_post_property_json(int devid, char *json, int timeout_ms, void (*func)(int retval, void *ctx), void *ctx);

用于网关或子设备主动上报属性到云端，该接口包括以下参数：

• devid: 设备ID；

• property: 输入参数，属性值，使用json格式表示，形如{"WorkMode": 1, "LightSwitch": 0}，以'\0'结尾；

• timeout：云端响应的超时时间，以毫秒为单位，为0则不等待云端响应；

• cb：接口调用失败或成功时调用的回调函数，retval = 0表示超时，retval < 0表示云端响应错误，retval = 1表示成功；

• ctx：传递给cb的用户私有数据；

上传raw data

int linkkit_gateway_post_rawdata(int devid, void *data, int len);

用户上传网关或子设备的裸数据，其中：

• devid：设备ID。该接口既可以用于网关，也可以用于子设备向云端发送事件；

• data：裸数据；

• len：裸数据长度；

扩展信息上报

typedef struct {
    char *attrKey;    /* the key of extend info. */
    char *attrValue;  /* the value of extend info. */
} linkkit_extinfo_t;

int linkkit_gateway_post_extinfos(int devid, linkkit_extinfo_t *extinfos, int nb_extinfos, int timeout_ms);

扩展信息上报：

• devid：设备ID；

• extinfos：扩展信息数组；

• nb_extinfos：extinfos的数量；

• timeout_ms：同步等待云端响应的超时时间，以毫秒为单位，为0则不等待云端响应。

删除扩展信息

int linkkit_gateway_delete_extinfos(int devid, linkkit_extinfo_t *extinfos, int nb_extinfos, int timeout_ms);

删除扩展信息：

• devid: 设备ID；

• extinfos：扩展信息数组，忽略linkkit_extinfo_t中的attrValue；

• nb_extinfos：extinfos的数量；

• timeout_ms：同步等待云端响应的超时时间，以毫秒为单位，为0则不等待云端响应。

获取设备信息

设备信息用于表示设备的当前状态，设备信息用linkkit_devinfo_t表示。linkkit_devinfo_t的声明如下所示：

enum {
    LINKKIT_STATE_ENABLED  = 0, /* device is enabled by cloud  */
    LINKKIT_STATE_DISABLED,     /* device is disabled by cloud */
    LINKKIT_STATE_REMOVED,      /* device is deleted by cloud  */
};

typedef struct {
    char *productKey;   /* device's product key */
    char *deviceName;   /* device's device name */

    int   devtype;      /* Device Type: 0 - gateway, 1 - subdev */
    int   login;        /* Login State: 0 - logout,  1 - login  */
    int   state;        /* Device State: see LINKKIT_STATE_xxx  */
    int   online;       /* 0 - offline, 1 - online              */
} linkkit_devinfo_t;

linkkit_devinfo_t包括以下成员：

• productKey：设备标识三元组中的productKey；

• deviceName：设备标识三元组中的deviceName；

• d​evtype：设备类型，0为网关，1为子设备；

• login：设备是否已经登录，0为未登录，1为已经登录；

• state：设备状态，当前包括以下三个状态：

  • LINKKIT_STATE_ENABLED：设备未被禁用；
  • LINKKIT_STATE_DISABLED：设备被禁用；
  • LINKKIT_STATE_REMOVED：设备已被云端删除；

• online：设备是否在线，0为不在线，1为在线。

获取单个设备信息

以下接口用户获取单个设备信息：

int linkkit_gateway_get_devinfo(int devid, linkkit_devinfo_t *devinfo);

该接口对应的参数如下所示：

• devid：设备ID；

• devinfo：设备信息结构体，详见linkkit_devinfo_t；

以下接口用于获取多个设备信息：

int linkkit_gateway_get_num_devices(void);
int linkkit_gateway_get_devinfos(linkkit_devinfo_t *devinfos, int nb_devinfos);

其中linkkit_get_num_devices()用于获取已经注册到SDK中的总设备个数，linkkit_gateway_get_devinfos()用户获取设备信息列表。linkkit_gateway_get_devinfos()包含两个参数，其中devinfos为linkkit_devinfo_t数组，用于保存获取到的设备信息列表，nb_devinfos代表devinfos数组的长度，linkkit_gateway_get_devinfos()返回值为实际返回的设备信息个数。

设备复位

设备复位接口如下所示：

int linkkit_gateway_reset(int devid);

其中输入参数devid可以为网关的devid，也可以为设备devid。如果linkkit_gateway_reset()的输入参数为网关的devid，该接口将删除网关和子设备的绑定关系，同时也会在云端删除该网关的所有用户数据。如果linkkit_gateway_reset()的输入参数为子设备的devid，则会解除该子设备和网关的绑定关系，同时删除云端中与该子设备相关的用户数据。

linkkit_gateway_reset()返回值如下所示：

• 等于0：接口调用成功；

• 等于1：接口由于网络超时或断网等原因调用出错，网关SDK会在内部重新进行reset，直到reset成功为止，reset成功时会通过LINKKIT_EVENT_RESET_SUCCESS事件通知用户；

• 小于0：接口调用失败。

设备升级

网关SDK的OTA服务仅限于将云端的升级包下载到本地，并对升级包进行校验，并不会对设备进行升级，具体的升级操作需要用户完成。

FOTA服务初始化

FOTA服务使用以下接口进行初始化：

int linkkit_ota_service_init(const linkkit_ota_params *ota_params);

其中ota_params为linkkit_ota_service_init()的初始化参数，该参数声明如下所示：

typedef struct {
    int   (*get_firmware_version)(const char *productKey, const char *deviceName, char *version, int buff_len);
    void *(*start)(const char *productKey, const char *deviceName, const char *new_version, int file_size);
    int   (*write)(void *handle, unsigned char *data, int data_len);
    int   (*stop) (void *handle, int err);
} linkkit_ota_params;

linkkit_ota_params中各成员说明如下：

• get_firmware_version: 用于获取指定productKey和deviceName对应的设备的当前版本号，设备上线时会调用该接口告知云端当前设备的版本号。get_firmware_version回调的参数说明如下：

  • productKey: 待升级设备对应的productKey；
  • deviceName: 待升级设备对应的deviceName；
  • version: 用于保存用户返回的版本号；
  • buff_len: version对应的buffer的字节大小；

• start: 云端触发升级时首先会调用该回调，用于通知用户productKey和deviceName对应的设备有新的设备升级请求。该回调的返回值为用户分配的，用于保存此次升级上下文的私有数据。start回调的参数说明如下：

  • productKey: 待升级设备对应的productKey；
  • deviceName: 待升级设备对应的deviceName；
  • new_version: 新固件升级包的版本号；
  • file_size: 固件的字节大小。

• write: 云端下发的升级包会分成多个片段，该回调用于保存云端下发的固件升级包片段。write回调的参数说明如下：

  • handle: 由start回调返回的用于保存该次升级的上下文信息；
  • data: 云端下发的固件升级包片段；
  • data_len: 升级包片段的长度；

• stop: 升级包下发完成。stop回调的参数说明如下：

  • handle: 由start回调返回的用于保存该次升级的上下文信息；
  • err: 用于标识升级包下载是否出错，支持的错误码如下所示。

注意：只有在调用linkkit_gateway_init()之后才能够调用linkkit_ota_service_init()初始化FOTA服务。

FOTA服务反初始化

FOTA服务使用以下接口进行初始化：

int linkkit_ota_service_deinit(void);

调用该接口后，网关SDK不会对云端的升级请求进行响应和处理。

主动上报设备版本号

用户可以调用以下接口主动上报设备的版本号：

int linkkit_ota_report_version(const char *productKey, const char *deviceName, const char *version);

其中productKey和deviceName为设备的标识信息，version为设备的当前版本号。