C SDK V1.x版开发指南
更新时间：
LinkFace SDK封装了设备与物联网云平台的通讯协议，实现了人员信息增删查，人脸信息增删查和人脸检测/识别事件上云等功能。SDK采用C语言开发，对外提供静态库和动态库版本。
版本历史
详见发布记录
SDK头文件
源码如下：
#ifndef __LINKFACE_H_V1__
#define __LINKFACE_H_V1__
#include <stdint.h>
#ifdef __cplusplus
extern "C"
{
#endif
/// 人员角色。
typedef enum AliPersonRole {
/*! 未知。 */
ALI_PERSON_ROLE_UNKNOWN = -2,
/*! 所有角色。 */
ALI_PERSON_ROLE_ALL = -1,
/*! 普通人员。 */
ALI_PERSON_ROLE_NORMAL = 0,
/*! 白名单人员。 */
ALI_PERSON_ROLE_WHITE = 1,
/*! 黑名单人员。 */
ALI_PERSON_ROLE_BLACK = 2,
/*! 非普通人员。 */
ALI_PERSON_ROLE_NOT_NORMAL = 3,
/*! 非白名单人员。 */
ALI_PERSON_ROLE_NOT_WHITE = 4,
/*! 非黑名单人员。 */
ALI_PERSON_ROLE_NOT_BLACK = 5
} AliPersonRole;
/*注册人脸需要的字段*/
struct AliPerson {
/*! 人员ID。 */
char id[64];
/*! 人员姓名。 */
char name[1024];
/*! 人员角色。 */
enum AliPersonRole role;
/*! 人脸图片数据大小。单位：字节。 */
int faceimg_size;
/*! 人脸图像数据。 */
unsigned char *faceimg;
/*! 人脸特征数据 */
unsigned char **face_feature;
/*! 人脸特征数据个数 */
int face_feature_size;
/*! 当wg_card_id为0时，使用此字段作为韦根门禁卡号 */
int64_t long_card_id;
/*! 身份证号码 */
char id_card[36];
/*! 有效期起始时间。从1970年1月1日0时0分0秒到截止时间的秒数（0表示不使用）。 */
unsigned int term_start;
/*! 有效期截止时间。从1970年1月1日0时0分0秒到截止时间的秒数（-1表示无限期，0表示永久失效）。 */
unsigned int term;
};
/// 人脸比对状态。
enum AliMatchStatus {
/*! 比对失败。 */
ALI_MATCH_STATUS_FAILED = -1,
/*! 未进行比对。 */
ALI_MATCH_STATUS_NULL = 0,
/*! 比对成功。 */
ALI_MATCH_STATUS_SUCCESS = 1,
};
/// 图片格式。
enum AliPictureFormat {
/*! 未知 */
ALI_PICTURE_FORMAT_NULL = -1,
/*! Jpg。 */
ALI_PICTURE_FORMAT_JPG = 0,
};
/// 性别。
enum AliSex {
/*! 未知 */
ALI_SEX_NULL = -1,
/*! 男。 */
ALI_SEX_MALE = 0,
/*! 女。 */
ALI_SEX_FEMALE = 1,
};
/*人脸对比上报*/
/*注册人脸需要的字段*/
struct AliMatcheResult {
/*! 点位编号。 */
char addr_id[32];
/*! 点位名称。 */
char addr_name[96];
/*! 设备编号。 */
char device_id[32];
/*! 抓拍时间（毫秒）。 */
uint64_t time_msec;
/*! 实时抓拍标志，历史识别事件传递参数0。[0：非实时抓拍][1：实时抓拍] */
int is_realtime;
/*! 比对状态。 必要字段。*/
enum AliMatchStatus match_status; //对比成功才会有人脸（即person_id,person_name，person_role，match_score）的值才有意义
/*! 人脸比对到的人员ID。 抓拍成功时，必要字段。*/
char person_id[64];
/*! 人脸比对到的人员姓名。 抓拍成功时，必要字段。*/
char person_name[255];
/*! 人员角色。 抓拍成功时，必要字段。*/
int person_role;
/*! 对比相似度。 抓拍成功时，必要字段。*/
int match_score;
/*! 全景图大小。 */
int panorama_img_size; //大小大于0时全景图的数据才有意义，否则全景图所有数据全部置空
/*! 全景图格式。 */
enum AliPictureFormat panorama_format;
/*! 人脸位于全景图像的X坐标。 */
unsigned short panorama_face_x;
/*! 人脸位于全景图像的Y坐标。 */
unsigned short panorama_face_y;
/*! 人脸位于全景图像的宽度。 */
unsigned short panorama_face_w;
/*! 人脸位于全景图像的高度。 */
unsigned short panorama_face_h;
/*! 全景图数据。必要字段。 */
char *panorama_img;
/*! 全景图名称。 必要字段。 */
char *panorama_img_name;
/*! 特写图大小。 */
int closeup_size; //大小大于0时特写图的数据才有意义，否则特写图所有数据全部置空
/*! 特写图格式。 */
enum AliPictureFormat closeup_format;
/*! 人脸位于特写图像的X坐标。 */
unsigned short closeup_face_x;
/*! 人脸位于特写图像的Y坐标。 */
unsigned short closeup_face_y;
/*! 人脸位于特写图像的宽度。 */
unsigned short closeup_face_w;
/*! 人脸位于特写图像的高度。 */
unsigned short closeup_face_h;
/*! 特写图数据。 */
char *closeup_img;
/*! 性别。 */
enum AliSex sex;
/*! 年龄。 */
unsigned char age;
/*! 是否佩戴安全帽 */
unsigned char hat;
/*! 安全帽颜色 */
unsigned char hat_color;
/*! 人脸扭转角度。 */
unsigned char turn_angle;
/*! 人脸平面旋转角度。 */
unsigned char rotate_angle;
/* 备用字段*/
unsigned char resv[3];
/*! 注册图大小。 */
int register_size;
/*! 注册图格式。 */
enum AliPictureFormat register_format;
/*! 注册图数据。 */
char *register_img;
/*! 设备序列号，唯一标识符。 */
char device_sn[32];
/*! 身份证信息标志。 */
int idcard_mark; //值为1才表示身份证信息相关的数据才有意义
/*! 号码。 */
char idcard_number[36];
/*! 姓名。 */
char idcard_name[64];
/*! 出生日期。 */
char idcard_data[18];
/*! 性别。 */
enum AliSex idcard_sex;
/*! 民族。 */
char idcard_nation[20];
/*! 住址。 */
char idcard_address[120];
/*! 签发机关。 */
char idcard_issue[44];
/*! 有效期起始时间。 */
char idcard_validityterm_start[18];
/*! 有效期截止时间。 */
char idcard_validityterm_end[18];
/*! 韦根门禁卡号 */
uint64_t long_card_id;
};
/* SDK日志等级 */
enum LinkfaceLogLevel {
/*! debug level */
ALI_LF_LOG_DEBUG = 0,
/*! info level */
ALI_LF_LOG_INFO = 1,
/*! warn level */
ALI_LF_LOG_WARN = 2,
/*! error level */
ALI_LF_LOG_ERROR = 3,
};
/* SDK日志输出类型 */
enum LinkfaceLogDest {
/*! 标准输出 */
ALI_LF_STDOUT = 0,
/*! 文件 */
ALI_LF_FILE = 1,
};
/* 日志配置 */
struct LinkfaceLogCfg {
/* 日志等级 */
enum LinkfaceLogLevel lvl;
/* 日志输出类型 */
enum LinkfaceLogDest dst;
/*! 日志文件保存路径 */
char *logpath;
/*! 日志存储目录大小Mb */
int max_size_log_mb;
};
/* sdk配置信息 */
struct LinkfaceConfig {
/*! productKey: 三元组之一, 详见物联网平台官方文档. */
char *productKey;
/*! productSecret: 产品密钥，一型一密时使用，否则填""， 详见物联网平台官方文档. */
char *productSecret;
/*! deviceName: 三元组之一, 详见物联网平台官方文档. */
char *deviceName;
/*! deviceSecret: 三元组之一, 详见物联网平台官方文档. */
char *deviceSecret;
/*! filePath: sdk会本地缓存一些配置信息，厂商需要确保此目录已存在且可写，预计占用物理空间2M以内。 */
char *filePath;
/*! 日志配置 */
struct LinkfaceLogCfg cfg_log;
};
/** 云端下发底库同步请求时，sdk会调用该接口将人脸底图信息逐个传递给厂商，厂商需要将该人脸添加到数据库中以
* 进行人脸识别。
* @brief 注册人脸数据接收回调函数格式定义。
* @param 注册人脸结构体。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
typedef int (*Ali_AddPersonDataCallback)(const struct AliPerson *person, void *user);
/** 云端需要删除某个人脸底库时，sdk会调用该接口将人脸信息逐个传递给厂商，厂商需要将该人脸从数据库中删除，
* 下次人脸检测时，该用户会因底库不存在该用户信息导致识别。
* @brief 删除人脸数据接收回调函数格式定义。
* @param 人脸id。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
typedef int (*Ali_DeletePersonDataCallback)(const char *person_id, void *user);
/** sdk调用本接口后，厂商需要清空人脸数据库。
* @brief 全量删除人脸回调函数。
* @param 用户数据。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
typedef int (*Ali_DeleteAllDataCallback)(void *user);
/** 注册添加人脸回调接口。
* @param callback 厂商需要实现的函数。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
void Ali_RegisterAddPerson(Ali_AddPersonDataCallback callback, void *user);
/** 注册删除人脸回调接口。
* @param callback 厂商需要实现的函数。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
void Ali_RegisterDeletePerson(Ali_DeletePersonDataCallback callback, void *user);
/** 注册全量删除人脸回调接口。
* @param callback 厂商需要实现的函数。
* @param user 用户参数，用户设置回调时指定的参数通过该参数再次回传给用户。
*/
void Ali_DeleteAll(Ali_DeleteAllDataCallback callback, void *user);
/** 当人脸门禁机检测到人脸后，无论是否能正确识别出该人脸，均需要调用本接口将识别结果上报到云端。
* @param result 识别结果，如果识别成功，需要包含已识别的人的基本信息。
*
* @return 成功返回0，其他值均为失败。
*/
int Ali_UploadMatchResult(const struct AliMatcheResult *result);
/** init 接口，必须首先调用，如果初始化失败，请sleep 1s后重试，直到成功。
* @param cfg: sdk配置信息
* 成功返回1，失败返回-1。
* */
int Ali_Init(struct LinkfaceConfig *cfg);
/** 进程退出前，释放sdk资源。
*/
void Ali_DeInit();
#ifdef __cplusplus
}
#endif
#endif
接口总览
SDK包内容介绍
tree -L 4
.
├── CMakeLists.txt ---------演示如何链接linkface和linkkit的库，如何编译sample
├── LinkFace ---------linkface的库和使用的样例
│ ├── samples ---------linkface使用的样例
│ │ ├── v1 ---------v1版本使用的样例
│ │ │ ├── 1.jpg ---------模拟人脸抓拍事件上云图片
│ │ │ ├── link_face_demo_v1 ---------v1版本演示可执行文件
│ │ │ ├── linkface_demo_v1.c ---------v1版本sample
│ │ │ ├── linkkit_adapter_v1.c ---------v1版本自定义集成linkkit的上云能力
│ │ │ ├── log_util.c
│ │ │ └── log_util.h
│ │ └── v2 ---------v2版本使用的样例
│ │ ├── 1.jpg
│ │ ├── database.c ---------v2版本基于sqlite完成了人脸底库的本地存储
│ │ ├── database.h
│ │ ├── link_face_demo_v2 ---------v2版本演示可执行文件
│ │ ├── linkface_demo_v2.c ---------v2版本sample
│ │ ├── linkkit_adapter_v2.c ---------v2版本自定义集成linkkit的上云能力
│ │ └── list.h
│ └── sdk
│ ├── v1
│ │ ├── liblinkface_v1.a ----------v1版本对外提供的动态库
│ │ ├── liblinkface_v1.so ----------v1版本对外提供的静态库
│ │ └── linkface_sdk_v1.h ----------v1版本对外提供的头文件
│ └── v2
│ ├── alarm_event_post_task.h
│ ├── event_cache_manager.h
│ ├── face_add_task.h
│ ├── facebase_manager.h
│ ├── face_cache_manager.h
│ ├── face_download_task.h
│ ├── liblinkface_v2.a ----------v2版本对外提供的动态库
│ ├── liblinkface_v2.so ----------v2版本对外提供的静态库
│ ├── linkface_sdk_v2.h ----------v2版本对外提供的头文件
│ └── net_protocol.h
└── third_party
├── cJSON ----------依赖的cjson库
│ ├── cJSON.h
│ ├── libcjson.a
│ ├── libcjson.so
│ ├── libcjson.so.1
│ └── libcjson.so.1.7.7
├── cJSON-1.7.7.tar.gz
├── linkkit-sdk-c ----------依赖的linkkit库
│ ├── exports
│ │ ├── iot_export_awss.h
│ │ ├── iot_export_coap.h
│ │ ├── iot_export_compat.h
│ │ ├── iot_export_errno.h
│ │ ├── iot_export_event.h
│ │ ├── iot_export_http2.h
│ │ ├── iot_export_http2_stream.h
│ │ ├── iot_export_http.h
│ │ ├── iot_export_linkkit.h
│ │ ├── iot_export_mqtt.h
│ │ ├── iot_export_ota.h
│ │ ├── iot_export_shadow.h
│ │ ├── iot_export_state.h
│ │ ├── linkkit_export.h
│ │ └── linkkit_gateway_export.h
│ ├── imports
│ │ ├── iot_import_awss.h
│ │ ├── iot_import_config.h
│ │ ├── iot_import_crypt.h
│ │ ├── iot_import_dtls.h
│ │ ├── iot_import_ota.h
│ │ ├── iot_import_product.h
│ │ ├── iot_import_tcp.h
│ │ ├── iot_import_tls.h
│ │ └── iot_import_udp.h
│ ├── iot_export.h
│ ├── iot_import.h
│ ├── libiot_hal.a
│ ├── libiot_sdk.a
│ └── libiot_tls.a
├── linkkit-sdk-c.tar.gz
├── release
│ ├── apr
│ │ ├── bin
│ │ ├── build-1
│ │ ├── include
│ │ └── lib
│ ├── apr_util
│ │ ├── bin
│ │ ├── include
│ │ └── lib
│ ├── curl
│ │ ├── bin
│ │ ├── include
│ │ ├── lib
│ │ └── share
│ ├── expat
│ │ ├── bin
│ │ ├── include
│ │ ├── lib
│ │ └── share
│ ├── iconv
│ │ ├── bin
│ │ ├── include
│ │ ├── lib
│ │ └── share
│ ├── mxml
│ │ ├── include
│ │ ├── lib
│ │ └── share
│ ├── openSSL
│ │ ├── bin
│ │ ├── include
│ │ └── lib
│ ├── oss_c_sdk
│ │ ├── include
│ │ └── lib
│ └── zlib
│ ├── include
│ ├── lib
│ └── share
├── sqlite ----------依赖的sqlite库
│ ├── libsqlite3.a
│ ├── libsqlite3.so
│ └── sqlite3.h
└── sqlite-amalgamation-3310100.tar.gz快速使用指南
下面来基于Ubuntu 16.04的环境来描述如何运行官方Sample。
解压
tar zxvf link_face_xxx_.tar.gz编译
我们提供了CMakeLists.txt来演示如何使用sdk，若单独使用sdk，请参考CMakeLists.txt来完成库的链接。
cd link_face_xxx_
mkdir build
cd build
cmake ../
make运行
cp link_face_demo_v1 ../LinkFace/samples/v1
./link_face_demo_v1 ${Product_Key} ${Device_Name} ${Device_Secret} ./
${Product_Key} ${Device_Name} ${Device_Secret} 分别替换成在物联网平台上申请的三元组即可。文档内容是否对您有帮助？