AI 助理
备案控制台
文档
输入文档关键字查找
首页 物联网应用服务（文档停止维护） 开发参考 开放能力 智能通行服务 设备接入 门禁SDK C SDK V4.x版开发指南

C SDK V4.x版开发指南

更新时间：
我的收藏

LinkGuard C SDK封装了设备与物联网云平台的通讯协议，实现了人员信息增删查和人员通行检测/识别事件上云等功能。SDK采用C语言开发，对外提供静态库和动态库版本。

版本历史

详见发布记录

SDK头文件

具体源码如下：

#ifndef __LINKGUARD_SDK__
#define __LINKGUARD_SDK__

#include <stdio.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C"
{
#endif

#define LG_API_PUBLIC __attribute__((visibility ("default")))

/**
 * 用户角色枚举
 */
typedef enum iotx_user_role_t {
    /* 未知 */
    USER_ROLE_UNKNOWN = -2,

    /* 所有角色 */
    USER_ROLE_ALL = -1,

    /* 普通用户 */
    USER_ROLE_NORMAL = 0,

    /* 白名单用户 */
    USER_ROLE_WHITE = 1,

    /* 黑名单用户 */
    USER_ROLE_BLACK = 2,

    /* 非普通用户 */
    USER_ROLE_NOT_NORMAL = 3,

    /* 非白名单用户 */
    USER_ROLE_NOT_WHITE = 4,

    /* 非黑名单用户 */
    USER_ROLE_NOT_BLACK = 5,
} iotx_user_role_t;

/**
 * 通行比对状态枚举
 */
typedef enum iotx_match_status_t {
    /* 比对失败 */
    MATCH_STATUS_FAILED = -1,

    /* 未进行比对 */
    MATCH_STATUS_NULL = 0,

    /* 比对成功 */
    MATCH_STATUS_SUCCESS = 1,
} iotx_match_status_t;

/**
 * 图片格式枚举
 */
typedef enum iotx_picture_format_t {
    /* 未知 */
    PICTURE_FORMAT_NULL = -1,

    /* JPG */
    PICTURE_FORMAT_JPG = 0,
} iotx_picture_format_t;

/**
 * SDK日志级别
 */
typedef enum iotx_log_level_t {
    /* debug level */
    LF_LOG_DEBUG = 0,

    /* info level */
    LF_LOG_INFO = 1,

    /* warn level */
    LF_LOG_WARN = 2,

    /* error level */
    LF_LOG_ERROR = 3,
} iotx_log_level_t;

/**
 * SDK日志输出类型
 */
typedef enum iotx_log_dest_t {
    /* 标准输出 */
    LF_STDOUT = 0,

    /* 文件 */
    LF_FILE = 1,
} iotx_log_dest_t;

/**
 * 注册用户需要的信息
 */
struct iotx_user_info_t {

    /* 用户ID */
    char id[64];

    /* 用户姓名 */
    char name[1024];

    /* 用户角色 */
    enum iotx_user_role_t role;

    /* 门禁身份认证图片数据大小 */
    int certified_pic_size;

    /* 门禁身份认证图片图像数据 */
    unsigned char *certified_pic;

    /* 图片特征数据 */
    unsigned char **pic_feature;

    /* 图片特征数据个数 */
    int pic_feature_size;
};

/**
 * 通行上报信息
 */
struct iotx_matche_result_t {

    /* 设备编号 */
    char device_id[32];

    /* 抓拍时间（毫秒） */
    uint64_t time_msec;

    /* 实时抓拍标志，历史识别事件传递参数0。[0：非实时抓拍][1：实时抓拍] */
    int is_realtime;

    /* 比对状态。必要字段。 */
    enum iotx_match_status_t match_status;

    /* 比对成功的用户ID。抓拍成功时，必填字段。 */
    char user_id[64];

    /* 比对成功的用户姓名。抓拍成功时，必填字段。 */
    char user_name[255];

    /* 比对成功的用户角色。抓拍成功时，必填字段。 */
    int user_role;

    /* 对比相似度，抓拍成功时，必填字段。 */
    int match_score;

    /* 全景图大小 */
    size_t panorama_pic_size;

    /* 全景图格式 */
    enum iotx_picture_format_t panorama_format;

    /* 全景图数据。必填字段。 */
    char *panorama_pic;

    /* 全景图名称。必填字段。 */
    char *panorama_pic_name;

};

/**
 * SDK日志配置
 */
struct iotx_log_cfg_t {

    /* 日志等级 */
    enum iotx_log_level_t lvl;

    /* 日志输出类型 */
    enum iotx_log_dest_t dst;

    /* 日志文件保存路径 */
    char *log_path;

    /* 日志存储目录大小为MB */
    int max_size_log_mb;
};

/**
 * SDK配置信息
 */
struct iotx_lg_config_t {

    /* 用公共实例，该参数要设置为1。若用独享实例，要将该参数设置为0。*/
    int8_t public_instance;

    /* 阿里云平台上海站点的域名后缀。如果是企业实例，要改成企业实例的接入点。*/
    char *mqtt_url;

    /* 阿里云平台上海站点的http2域名后缀 */
    char *http2_url;

    /* product_key：三元组之一，详见物联网平台官方文档。*/
    char *product_key;

    /* product_secret：产品密钥，一型一密时使用，否则填""，详见物联网平台官方文档。*/
    char *product_secret;

    /* device_name：三元组之一，详见物联网平台官方文档。*/
    char *device_name;

    /* device_secret：三元组之一，详见物联网平台官方文档。*/
    char *device_secret;

    /* data_path: SDK会本地缓存配置信息，厂商需要确保此目录存在且可写，预计占用物理空间2M以内。*/
    char *data_path;

    /* 更新数据模式。[0：重复不更新][1：强制更新] */
    int update_mode;

    /* 日志配置 */
    struct iotx_log_cfg_t cfg_log;

    /* 外部初始化LinkSDK，需要把mqtt_handle赋值给LinkGuard SDK。 */
    void *mqtt_handle;

    /* 外部初始化LinkSDK，需要把dm_handle赋值给LinkGuard SDK。 */
    void *dm_handle;

};

/**
 * 获取不同环境mqtt host url
 * @param cfg SDK配置信息
 */
static inline void mqtt_host(const struct iotx_lg_config_t *cfg, char *host) {
#ifdef ON_PRE
    snprintf(host, 100, "%s", "iot-test-pre-ha.iot-as-mqtt.unify.aliyuncs.com");
#endif
#ifdef ON_ONLINE
    if (1 == cfg->public_instance) {
        snprintf(host, 100, "%s.%s", cfg->product_key, cfg->mqtt_url);
    } else {
        snprintf(host, 100, "%s", cfg->mqtt_url);
    }
#endif
}

/**
 * 获取不同环境http2 host url
 * @param cfg SDK配置信息
 */
static inline void http2_host(const struct iotx_lg_config_t *cfg, char *host, uint16_t *port) {
#ifdef ON_PRE
    snprintf(host, 100, "%s", "121.196.243.216");
    *port = 8443;
#endif
#ifdef ON_ONLINE
    snprintf(host, 100, "%s.%s", cfg->product_key, cfg->http2_url);
#endif
}

/**
 * SDK初始化接口，需首先调用，如果初始化失败，请sleep 1s后重试，直到成功。
 * @param cfg SDK配置信息
 * @return [1：成功][-1：失败][-2：参数错误]
 */
LG_API_PUBLIC int iotx_lg_init(struct iotx_lg_config_t *cfg);

/**
 * 进程退出时，可释放SDK资源。
 */
LG_API_PUBLIC void iotx_lg_deinit();

/**
* 云端添加用户信息请求时，SDK调用回调将用户信息逐个传递给厂商，厂商需要将该用户添加到数据库中进行身份识别。
* @param user_info 用户信息
*/
typedef int (*add_user_info_callback)(const struct iotx_user_info_t *user_info);

/**
* 云端删除用户信息请求时，SDK调用回调接口将用户信息逐个传递给厂商，厂商需要将用户从数据库中删除。
* @param user_id 删除用户信息ID
*/
typedef int (*delete_user_info_callback)(const char *user_id);

/**
* SDK调用回调接口，厂商需要清空用户数据库。
*/
typedef int (*delete_all_data_callback)();

/**
 * 注册用户信息添加回调接口
 * @param callback 添加回调接口
 */
LG_API_PUBLIC void register_add_user(add_user_info_callback callback);

/**
* 注册用户信息删除回调接口
* @param callback 删除回调接口
*/
LG_API_PUBLIC void register_delete_user(delete_user_info_callback callback);

/**
* 注册用户信息全量删除回调接口
* @param callback 全量删除回调接口
*/
LG_API_PUBLIC void register_delete_all(delete_all_data_callback callback);

/**
 * 当门禁机检测到用户后，无论是否能正确识别出该用户，均需要调用本接口将识别结果上报到云端。如果断网续传的历史识别事件，需要设置is_realtime为0。
 * @param result 识别结果，如果识别成功，需要包含已识别的人的基本信息。
 * @return 上报结果[0：成功][-1：失败]
 */
LG_API_PUBLIC int upload_match_result(const struct iotx_matche_result_t *result);

#ifdef __cplusplus
}
#endif

#endif

接口总览

yuque_diagram (1)

SDK包内容介绍

tree -L 3
.
├── CMakeLists.txt               ---------演示如何链接LinkGuard SDK和Link SDK的库，如何编译sample
├── LinkGuard
│   ├── samples                  ---------LinkGuard的库和使用的样例
│   │   ├── aiot.jpg             ---------模拟人脸抓拍事件上云图片
│   │   ├── linkguard_demo       ---------演示可执行文件
│   │   ├── linkguard_demo.c     ---------sample代码
│   │   └── linksdk_adapter.c    ---------自定义集成Link SDK的上云能力
│   └── sdk
│       ├── common               ----------基础库头文件
│       ├── liblinkguard.a       ----------LinkGuard动态库
│       ├── liblinkguard.so      ----------LinkGuard静态库
│       ├── linkguard_sdk.h      ----------LinkGuard头文件
│       ├── portfiles            ----------底层软硬件资源接口 
│       └── version.h            ----------版本号信息
└── third_party
    └── release
        ├── LinkSDK-v4x          ----------依赖LinkSDK v4x头文件
        └── cJSON              ----------依赖cJSON头文件

快速使用指南

下面来基于Ubuntu 16.04的环境来描述如何运行官方Sample。

  • 解压

tar zxvf linkguard_xxx_xxx.tar.gz

  • 编译

我们提供了CMakeLists.txt来演示如何使用sdk，若单独使用sdk，请参考CMakeLists.txt来完成库的链接。

cd linkguard_xxx_xxx

mkdir build

cd build

cmake ../

make

  • 运行

./linkguard_demo ${Product_Key} ${Device_Name} ${Device_Secret} /data/path /log/path

${Product_Key} ${Device_Name} ${Device_Secret} 分别替换成在物联网平台上申请的三元组即可。

上一篇：C SDK V1.x版开发指南下一篇：Android SDK v1.1接口说明
文档推荐