更新时间:2022-05-18 GMT+08:00
分享

接口函数

表1 edge.h中支持的接口函数

接口

说明

edge_init

初始化sdk的工作环境,加载证书、读取配置等

edge_set_callbacks

注册回调接口,登录、子设备添加、删除、设备消息、设备命令等都是异步通知的,故需要注册对应的处理函数

edge_login

用于SDK登录边缘,该函数是异步函数,登陆成功会调用4.2章节中已注册的pfn_connected回调函数

edge_logout

用于SDK登出边缘

edge_destroy

用于清理SDK资源

edge_send_add_sub_device

网关添加子设备,可批量添加

edge_send_delete_sub_device

删除子设备,可批量删除

edge_send_batch_device_data

批量上报子设备数据,可以同时上报多个设备的多个service数据

edge_send_batch_device_data_v2

该接口主要用于上报单个设备单服务的属性数据

edge_send_batch_device_data_v3

上报子设备数据,自行构造json数据

edge_send_command_rsp

用于响应平台下发的设备命令

edge_send_get_sub_device_shadow

用于网关发送请求给平台获取子设备影子

edge_send_sub_device_event

用于网关给平台发送子设备事件

edge_send_get_product

用于网关给平台发送获取产品的请求

edge_send_sub_device_property_get_rsp

用于网关响应平台的子设备属性获取请求

edge_send_sub_device_property_set_rsp

用于网关响应平台的子设备属性设置请求

edge_send_customized_message

用于网关发送自定义topic消息

edge_set_bus_message_cb

为消息总线输入点设置回调函数

edge_send_bus_message

向消息总线输出点发送数据

edge_call_device_command

调用产品模型里定义的命令

详细接口说明参见代码解析

include目录下的头文件edge.h,包括所有C SDK提供的回调函数和接口。以下是具体函数介绍。

edge.h回调函数说明

  1. 模块影子数据回调

    函数描述:

    typedef  EDGE_RETCODE (FN_SHADOW_ARRIVED)(const char* shadow, unsigned int shadow_len);

    函数功能:

    当下发模块配置时,通过此函数通知到用户,用户应用的配置也通过此函数通知。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    shadow

    char*

    模块影子数据(json字符串),第三方应用下发用户的配置数据

    {

    “config”:”test”

    }

    shadow_len

    unsigned int

    影子数据的长度

    -

  2. 命令下发回调

    函数描述:

    typedef EDGE_RETCODE (FN_COMMAND_ARRIVED)(const char* command_name, const char* device_id, const char* service_id, const char* request_id, const char* body, unsigned int body_len);

    函数功能:

    此函数声明用户命令下发通知,设备命令下发即使用此函数声明。

    参数说明:

    参数名称

    类型

    参数描述

    command_name

    char*

    设备命令名称,在设备关联的产品模型中定义。

    device_id

    char*

    命令对应的目标设备ID,命令下发对应的最终目标设备

    service_id

    char*

    设备的服务ID,在设备关联的产品模型中定义

    request_id

    char*

    {request_id}用于唯一标识这次请求,响应该命令时需要带上。

    body

    char*

    json字符串,设备命令的执行参数,具体字段在设备关联的产品模型中定义

    body_len

    unsigned int

    -

  3. 消息下发回调

    函数描述:

    typedef  EDGE_RETCODE (FN_MESSAGE_ARRIVED)(const char* message_id, const char* message_name, const char* device_id, const char* body, unsigned int body_len);

    函数功能:

    此函数声明用于消息下发通知,平台使用此接口承接平台下发给设备的自定义格式的数据。

    参数说明:

    参数名称

    类型

    参数描述

    message_id

    char*

    消息名称

    message_name

    char*

    消息的唯一标识

    device_id

    char*

    命令对应的目标设备ID,命令下发对应的最终目标设备

    body

    char*

    消息内容。

    body_len

    unsigned int

    消息长度

  4. 事件下发回调

    函数描述:

    typedef  EDGE_RETCODE (FN_DEVICE_EVENT_ARRIVED)(const char* device_id, const char* body, unsigned int body_len);

    函数功能:

    此函数声明用于事件下发通知,平台使用此接口承接平台下发给设备的自定义格式的数据。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    device_id

    char*

    命令对应的目标设备ID,命令下发对应的最终目标设备

    -

    body

    char*

    事件内容。

    {

    "object_device_id":"deviceId",

    "services":[

    {

    "service_id":"serviceTest",

    "event_id":"eventTest",

    "event_type":"eventTypeTest",

    "event_time":"time",

    "paras":{

    "test":"test"

    }

    }

    ]

    }

    body_len

    unsigned int

    消息长度

    -

  5. 子设备添加回调

    函数描述:

    typedef  EDGE_RETCODE (FN_SUB_DEVICE_ADD_ARRIVED)(const char* addSubDeviceInfo, unsigned int body_len);

    函数功能:

    此函数声明用于通知子设备添加,使用此接口承接平台添加成功子设备的通知。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    addSubDeviceInfo

    char*

    添加成功的子设备信息,具体格式见示例

    {"devices":

    [{"parent_device_id":"c6b39067b03421a48",

    "node_id": "subdevice11",

    "device_id":"2bb77-063ad2f5a6cc",

    "name": "subDevice11",

    "description": null,

    "product_id":"c6b3b34663d3ea42f6",

    "fw_version": null,

    "sw_version": null,

    "status": "ONLINE"

    }],"version":1}

    body_len

    unsigned int

    长度

    -

  6. 子设备删除回调

    函数描述:

    typedef  EDGE_RETCODE (FN_SUB_DEVICE_DELETED_ARRIVED)(const char* deleteSubDeviceInfo, unsigned int body_len);

    函数功能:

    此函数声明用于通知子设备删除,使用此接口承接平台删除成功子设备的通知。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    deleteSubDeviceInfo

    char*

    删除成功的子设备信息,具体格式见示例

    {"devices":

    [{"parent_device_id":"c6b39067b03421a48",

    "node_id": "subdevice11",

    "device_id":"2bb77-063ad2f5a6cc",

    "name": "subDevice11",

    "description": null,

    "product_id":"c6b3b34663d3ea42f6",

    "fw_version": null,

    "sw_version": null,

    "status": "ONLINE"

    }],"version":1}

    body_len

    unsigned int

    长度

    -

  7. 子设备扫描回调

    函数描述:

    typedef  EDGE_RETCODE (FN_START_SCAN_ARRIVED)(const char* protocol, const char* channel, const char* parentDeviceId,const char* scan_setting, unsigned int body_len);

    函数功能:

    此函数声明用于通知网关扫描子设备。

    参数说明:

    参数名称

    类型

    参数描述

    protocol

    char*

    协议

    channel

    char*

    通道信息

    parentDeviceId

    char*

    父设备ID

    scan_setting

    char*

    扫描设备

    body_len

    unsigned int

    配置长度

  8. 子设备属性设置回调

    函数描述:

    typedef  EDGE_RETCODE (FN_DEVICE_PROPERTIES_SET_ARRIVED)(ST_PROPERTY_SET* sub_device_property_set);

    函数功能:

    此函数声明用于接收平台对子设备的属性设置。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    sub_device_property_set

    ST_PROPERTY_SET*

    属性设置

    参见edge.h

  9. 子设备属性获取回调

    函数描述:

    typedef  EDGE_RETCODE (FN_DEVICE_PROPERTIES_GET_ARRIVED)(ST_PROPERTY_GET* sub_device_property_get);

    函数功能:

    此函数声明用于接收平台获取子设备的属性。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    sub_device_property_get

    ST_PROPERTY_GET*

    属性设置

    参见edge.h

  10. 子设备影子回调

    函数描述:

    typedef  EDGE_RETCODE (FN_DEVICE_SHADOW_ARRIVED)(ST_DEVICE_SHADOW* sub_device_shadow);

    函数功能:

    此函数声明用于接收平台设置子设备的影子。

    参数说明:

    参数名称

    类型

    参数描述

    示例

    sub_device_property_get

    ST_DEVICE_SHADOW*

    属性设置

    参见edge.h

  11. 自定义topic消息通知回调

    函数描述:

    typedef  EDGE_RETCODE (FN_CUSTOMIZED_MESSAGE_ARRIVED)(const char* topic, const char* payload, unsigned int len);

    函数功能:

    此函数声明用于接收平台设置子设备的影子。

    参数说明:

    参数名称

    类型

    参数描述

    topic

    char*

    自定义topic

    payload

    char*

    消息内容

    len

    unsigned int

    消息长度

edge.h的接口函数介绍

所有接口函数定义的数据结构均呈现在edge_struct.h头文件中。

1. 初始化

接口描述:

int  edge_init(const char* workdir)

接口功能:

初始化sdk的工作环境,加载证书、读取配置等

参数说明:

参数名称

类型

参数描述

示例

workdir

workdir

初始化文件所在目录,conf目录所在的目录,conf是存放证书文件以及日志配置的目录

conf在/code/api_test/workdir目录下,就填写/code/api_test/workdir

2. 注册回调接口

接口描述:

int edge_set_callbacks(ST_MODULE_CBS* module_cbs, ST_DEVICE_CBS* device_cbs)

接口功能:

注册回调接口,登录、子设备添加、删除、设备消息、设备命令等都是异步通知的,故需要注册对应的处理函数。

参数说明:

参数名称

类型

参数描述

module_cbs

ST_MODULE_CBS

模块回调函数结构体

device_cbs

ST_DEVICE_CBS

设备回调函数结构体

ST_MODULE_CBS模块相关的回调函数说明

参数名称

类型

参数描述

pfn_shadow_cb

FN_SHADOW_ARRIVED*

模块影子回调函数类型,模块的配置可以使该接口接收

pfn_command_cb

FN_COMMAND_ARRIVED*

发送到模块的命令的接收函数声明,

pfn_connected

FN_SDK_CONNECTED

SDK连接到边缘hub的回调函数声明

pfn_disconnected

FN_SDK_DISCONNECTED

SDK和边缘hub断链的回调函数声明

ST_DEVICE_CBS子设备相关的回调函数

参数名称

类型

参数描述

pfn_device_message_cb

FN_MESSAGE_ARRIVED*

子设备消息回调

pfn_device_command_cb

FN_COMMAND_ARRIVED*

子设备命令回调

pfn_device_event_cb

FN_DEVICE_EVENT_ARRIVED*

子设备事件回调

pfn_sub_device_add_cb

FN_SUB_DEVICE_ADD_ARRIVED*

子设备添加通知回调

pfn_sub_device_deleted_cb

FN_SUB_DEVICE_DELETED_ARRIVED*

子设备删除通知回调

pfn_on_start_scan_cb

FN_START_SCAN_ARRIVED*

收到子设备扫描通知回调

pfn_device_properties_set_cb

FN_DEVICE_PROPERTIES_SET_ARRIVED*

收到子设备属性设置通知回调

pfn_device_properties_get_cb

FN_DEVICE_PROPERTIES_GET_ARRIVED*

收到子设备属性获取通知回调

pfn_device_shadow_cb

FN_DEVICE_SHADOW_ARRIVED*

收到子设备影子

3. 登录

接口描述:

int edge_login()

接口功能:

用于SDK登录边缘,该函数是异步函数,登陆成功会调用4.2章节中已注册的pfn_connected回调函数。

4. 登出

接口描述:

void edge_logout()

接口功能:

用于SDK登出边缘

5. 清理

接口描述:

void edge_destroy()

接口功能:

用于清理SDK资源。

6. 网关添加子设备

接口描述:

int edge_send_add_sub_device(ST_DEVICE_INFO* device_info, unsigned int size)

接口功能:

网关添加子设备,可批量添加,device_info为ST_DEVICE_INFO数组,size为数组的大小(个数);

参数描述:

参数名称

类型

参数描述

示例

device_info

ST_DEVICE_INFO

设备信息

参见edge.h

size

Int

数组个数

-

备注:

该接口的调用成功不代表添加成功,仅仅代表添加子设备的请求发送到hub,设备的添加成功与否需要edge.h中注册的设备回调接口pfn_sub_device_add_cb。

样例:

[{
"parent_device_id": "c6b39067b0325db34663d3ef421a42f6_12345678",
"node_id": "subdevice11",
"device_id": "2bb4ddba-fb56-4566-8577-063ad2f5a6cc",
"name": "subDevice11",
"description": null,
"product_id": "c6b39067b0325db34663d3ef421a42f6",
"fw_version": null,
"sw_version": null,
"status": "ONLINE"
}]

7. 网关删除子设备

接口描述:

int edge_send_delete_sub_device (ST_DEVICE_INFO* device_info, unsigned int size)

接口功能:

删除子设备,可批量删除,device_info为ST_DEVICE_INFO数组,size为数组的大小(个数);

参数描述:

参数名称

类型

参数描述

示例

device_info

ST_DEVICE_INFO

设备信息

-

size

Int

数组个数

-

备注:

该接口的调用成功不代表删除成功,仅仅代表删除子设备的请求发送到hub,设备的删除成功与否需要edge.h中注册的设备回调接口pfn_sub_device_deleted_cb。

样例:

[{
"parent_device_id": "c6b39067b0325db34663d3ef421a42f6_12345678",
"node_id": "subdevice11",
"device_id": "2bb4ddba-fb56-4566-8577-063ad2f5a6cc",
"name": "subDevice11",
"description": null,
"product_id": "c6b39067b0325db34663d3ef421a42f6",
"fw_version": null,
"sw_version": null,
"status": "ONLINE"
}]

8. 设备数据批量上报v1

接口描述:

int edge_send_batch_device_data(ST_DEVICE_SERVICE* devices,unsigned int size)

接口功能:

批量上报子设备数据,可以同时上报多个设备的多个servicce数据,devices为ST_DEVICE_SERVICE数组,size为数组的个数;

参数描述:

参数名称

类型

参数描述

devices

ST_DEVICE_SERVICE

设备数据

size

Int

数组个数

样例:

ST_DEVICE_SERVICE样式

{
"device_id":"bf40f0c4-4022-41c6-a201-c5133122054a",
"services":[
{
"service_id":"analog",
"properties":{
"PhV_phsA":"1",
"PhV_phsB":"2"
},
"event_time":"20190606T121212Z"
}
]
}

9. 设备数据批量上报v2(单设备单serviceId上报)

接口描述:

int edge_send_batch_device_data_v2(const char *device_id, const char *service_id, const char *service_properties, const char *event_time)

接口功能:

该接口主要用于上报单个设备单服务的属性数据;

参数描述:

参数名称

类型

参数描述

示例

device_id

char*

设备ID

-

service_id

char*

服务Id

-

properties

char*

属性值(Json字符串)

-

event_time

char*

时间戳

"20190606T121212Z"

10. 设备数据批量上报v3(自行构造json体上报)

接口描述:

int edge_send_batch_device_data_v3(const char *service_properties, unsigned int size)

接口功能:

上报子设备数据,自行构造json数据;

参数描述:

参数名称

类型

参数描述

示例

service_properties

Json字符串

设备数据

-

size

Int

长度

-

样例:

service_properties数据格式如下:

[{
"device_id":"bf40f0c4-4022-41c6-a201-c5133122054a",
"services":[
{
"service_id":"test",
"properties":{
"PhV_phsA":"1",
"PhV_phsB":"2"
},
"event_time":"20190606T121212Z"
}
]
}]

11. 设备命令响应

接口描述:

int  edge_send_command_rsp(const char* rsp_name, const char* request_id, int result_code, const char* rsp_body, unsigned int body_lens);

接口功能:

用于响应平台下发的设备命令,该接口和"命令下发回调"搭配使用。

参数描述:

参数名称

类型

参数描述

示例

request_id

char*

长度

{request_id}用于唯一标识这次请求,匹配下发的命令,

rsp_name

char*

命令响应名称

命令的响应名称,在设备关联的产品模型中定义

result_code

char*

命令响应码

标识命令的执行结果,0表示成功,其他表示失败。不带默认认为成功。

rsp_body

char*

响应参数

命令的响应参数,具体字段在设备关联的产品模型中定义。

body_lens

unsigned int

rsp_body长度

-

12. 获取子设备影子

接口描述:

int edge_send_get_sub_device_shadow(const char* request_id, ST_DEVICE_SHADOW_GET* device_shadow_get);

接口功能:

用于网关发送请求给平台获取子设备影子,该接口和"子设备影子回调"搭配使用,请求后将通过"子设备影子回调"的回调函数通知到网关。

参数描述:

参数名称

类型

参数描述

示例

request_id

char*

长度

{request_id}用于唯一标识这次请求,

device_shadow_get

ST_DEVICE_SHADOW_GET*

获取影子结构

具体示例参见edge.h

13. 发送子设备消息

接口描述:

int  edge_send_sub_device_message(ST_DEVICE_MESSAGE* device_message);

接口功能:

用于网关给平台发送子设备消息;

参数描述:

参数名称

类型

参数描述

示例

device_message

ST_DEVICE_MESSAGE*

设备消息格式

具体示例参见edge.h

14. 发送子设备事件

接口描述:

int  edge_send_sub_device_event(ST_DEVICE_EVENT* device_event);

接口功能:

用于网关给平台发送子设备事件;

参数描述:

参数名称

类型

参数描述

示例

device_event

ST_DEVICE_EVENT*

设备事件格式

具体示例参见edge.h

15. 发送获取产品请求

接口描述:

int edge_send_get_product(const char** product_ids, unsigned int product_id_size);

接口功能:

用于网关给平台发送获取产品的请求;

参数描述:

参数名称

类型

参数描述

示例

product_ids

char**

产品id的数组列表

[

"productId1",

"productId2",

]

product_id_size

unsigned int

数组长度

-

16. 发送子设备属性获取响应

接口描述:

int edge_send_sub_device_property_get_rsp(const char* request_id, ST_DEVICE_PROPERTY_GET_RSP* device_property_get_rsp);

接口功能:

用于网关响应平台的子设备属性获取请求,和"子设备属性获取回调"回调请求搭配子设备属性获取回调子设备属性获取回调使用。

参数描述:

参数名称

类型

参数描述

示例

request_id

char*

请求id

{request_id}用于唯一标识这次请求,

device_property_get_rsp

ST_DEVICE_PROPERTY_GET_RS子设备属性获取回调P*

属性获取响应

参见edge.h

17. 发送子设备属性设置响应

接口描述:

int edge_send_sub_device_property_set_rsp(const char* request_id, ST_IOT_RESULT* iot_result);

接口功能:子设备属性设置回调

用于网关响应平台的子设备属性设置请求,和"子设备属性获取回调"回调请求搭配使用。

参数描述:

参数名称

类型

参数描述

示例

request_id

char*

请求id

{request_id}用于唯一标识这次请求,

iot_result

ST_IOT_RESULT*

属性设置响应

参见edge.h子设备属性获取回调

18. 发送自定义topic消息

接口描述:

int edge_send_customized_message(const char* topic, const char* body, unsigned int body_len);

接口功能:

用于网关发送自定义topic消息。

参数描述:

参数名称

类型

参数描述

topic

char*

自定义topic

body

char*

消息体

body_len

unsigned int

消息长度

图示:

解释:

用户在调用设备接入的自定义消息时,注册的自定义topic需要附加上/modules/{moduleId}/前缀。

19. 设置发送总线消息回调

接口描述:

int edge_set_bus_message_cb(const char* input_name);

接口功能

为消息总线输入点设置回调函数。

参数描述:

参数名称

类型

参数描述

示例

input_name

char*

消息总线输入点

见Demo

20. 发送总线消息

接口描述:

edge_send_bus_message(const char* output_name, const char* body, unsigned int body_len);

接口功能:

向消息总线输出点发送数据。

参数描述:

参数名称

类型

参数描述

output_name

char*

消息总线输出点

body

char*

消息体

body_len

unsigned int

消息长度

21. 调用设备命令

接口描述

int   edge_call_device_command(ST_COMMAND* command, unsigned int timeout);

接口功能:

调用产品模型里定义的命令。

参数描述:

参数名称

类型

参数描述

示例

command

ST_COMMAND*

设备命令

{

"device_123",

"power",

"restart"

}

timeout

unsigned int

超时参数(以秒为单位)

-

分享:

    相关文档

    相关产品

close