网关API使用说明
更新时间:2018-05-28 16:38:15
结构体
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;
} event_data;
} linkkit_event_t;
linkkit_event_t用于表示网关SDK内部事件,包括以下成员:
- event_type:事件类型,支持的事件类型如下表所示:
事件类型
|
说明
|
LINKKIT_EVENT_CLOUD_DISCONNECTED
|
设备断开阿里IoT云
|
LINKKIT_EVENT_CLOUD_CONNECTED
|
设备连接上阿里IoT云。在连上IoT云时,应该post设备的所有属性,确保云端的影子设备与设备端同步
|
LINKKIT_EVENT_SUBDEV_DELETED
|
云端删除子设备,删除的子设备由event_data的subdev_deleted指定
|
LINKKIT_EVENT_SUBDEV_PERMITED
|
允许zigbee子设备接入网关。允许接入网关的子设备由event_data的subdev_permited指定,如果product Key为NULL,则允许所有子设备接入,如果productKey不为NULL,则只允许productKey为对应值的子设备接入。timeoutSec为允许子设备接入的时间窗口。如果timeoutSec为0,则禁止子设备接入。
|
LINKKIT_EVENT_SUBDEV_SETUP
|
ZigBee网关置换专用,用户在APP端触发网关置换请求,云端通过属性设置接口设置ZigBee网络参数到新的网关,再从云端同步被置换网关子设备信息到新的网关,subdevList json字符串格式:[{"productKey":"","deviceName":""},...]
|
- 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_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的值类型和取值范围如下表所示:
option
|
说明
|
值类型
|
默认值
|
取值范围
|
LINKKIT_OPT_MAX_MSG_SIZE
|
设置最大消息长度
|
int
|
20480
|
512 - 51200
|
LINKKIT_OPT_MAX_MSG_QUEUE_SIZE
|
设置消息队列长度
|
int
|
16
|
2 - 32
|
LINKKIT_OPT_THREAD_POOL_SIZE
|
用于处理消息的线程池线程数,用户注册的回调会在线程池中调用
|
int
|
4
|
1 - 16
|
LINKKIT_OPT_THREAD_STACK_SIZE
|
线程池的线程栈栈大小
|
int
|
8192
|
1024-8388608
|
LINKKIT_OPT_LOG_LEVEL
|
日志打印等级,支持的日志等级包括:
|
int
|
4
|
0-5
|
注册事件回调
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 *identifer, char *event, int timeout, void (*cb)(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 *property, int timeout, void (*cb)(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;
devtype:设备类型,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()
返回值为实际返回的设备信息个数。