系统模块

最近更新时间：2021-07-05 11:08:40

我的收藏

本页目录：

功能介绍
本模块提供 SDK 读写目录，打印 log，设备性能和版本信息初始化，证书读写，设备上线及时间同步。
证书分为初始证书和激活证书，初始证书在生产时烧录进设备，只能激活一次，激活后的激活证书供设备线上功能使用，用户可以通过本模块实现设备初始证书烧写、读取，激活。具体读写方式由用户来实现，SDK 在需要时自行调用。
上线回调会传入服务器时间信息用于同步设备时间，精度为毫秒。
流程指引
系统模块总流程
初始化系统参数、注册读写证书、设备上线回调 > 系统初始化 > 设置当前时区 > 系统去初始化。
上线流程
设备连接服务器成功 > 回调设备上线函数 > 设置系统时间。
接口参考
该功能模块提供以下接口：
iv_sys_init：系统初始化。
iv_sys_exit：系统去初始化。
iv_sys_read_certificate_cb：读证书数据回调。
iv_sys_write_certificate_cb：写证书数据回调。
iv_sys_get_encrypt_lib_path_cb：获取烧写的加密库的绝对路径。
iv_sys_online_cb：设备上线回调函数。
iv_sys_offline_cb：设备离线回调函数。
iv_sys_get_utc_ms：用户自定义获取系统 UTC 时间函数，精确到 ms。
iv_sys_set_timezone：设置系统时区函数。
iv_sys_get_tid：获取设备 Tid。
iv_sys_set_net_interface：设置当前使用的网卡名。
iv_sys_sync_net_time_cb：同步网络时间回调。
iv_sys_get_pid：获取设备所属 Pid。
iv_sys_init
接口描述
系统资源的初始化。包括资源申请，系统参数及证书、上线回调初始化等，SDK 开始时调用。
int iv_sys_init(const iv_sys_init_parm_s *pstInitParm);
参数说明
参数名称
类型
描述
输入/输出
pstInitParm
iv_sys_init_parm_s*
初始化参数。
输入
返回值
返回值
描述
IV_ERR_NONE
成功。
IV_ERR_*
失败，对应相应 错误码。
iv_sys_exit
接口描述
系统资源去初始化，SDK 退出时调用。
int iv_sys_exit(void);
参数说明
无
返回值
返回值
描述
IV_ERR_NONE
成功。
IV_ERR_*
失败，对应相应 错误码。
iv_sys_read_certificate_cb
接口描述
读证书数据。用户需要实现读初始证书和激活证书功能，读取加密密钥库路径功能，SDK 需要时回调，注意应用层读取初始化证书和激活证书时返回的是证书内容，读取加密密钥库路径时返回库路径字符串内容。
int (* iv_sys_read_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t *pCertificateLen); |
参数说明
参数名称
类型
描述
输入/输出
eCertificateType
iv_sys_certificate_type_e
证书类型。
输入
pCertificateBuf
char *
证书数据内容。
输出
pCertificateLen
uint32_t *
证书数据长度。
输出
返回值
返回值
描述
IV_ERR_NONE
成功。
IV_ERR_*
失败，对应相应 错误码。
iv_sys_write_certificate_cb
接口描述
写入证书数据。用户需要实现写初始证书、激活证书和加密密钥库功能，SDK 需要时回调。
int (* iv_sys_write_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t u32CertificateLen); |
参数说明
参数名称
类型
描述
输入/输出
eCertificateType
iv_sys_certificate_type_e
证书类型。
输入
pCertificateBuf
char *
证书数据内容。
输入
u32CertificateLen
uint32_t
证书数据长度。
输入
返回值
返回值
描述
IV_ERR_NONE
成功。
IV_ERR_*
失败，对应相应 错误码。
iv_sys_online_cb
接口描述
设备上线回调，并会带入网络时间参数，用于同步时间，SDK 回调通知用户设备已经上线，用户根据携带的时间信息进行时间同步。
void (* iv_sys_online_cb)(uint64_t u64NetDateTime); 
参数说明
参数名称
类型
描述
输入/输出
u64NetDateTime
uint64_t
网络时间，距1970年毫秒数。
输入
返回值
返回值
描述
void
无返回值。
iv_sys_offline_cb
接口描述
IoT Video（Consumer Version） 设备失去与服务器的连接后，通过此回调通知上层。
【声明】
void (* iv_sys_offline_cb)(void); 
参数说明
无
返回值
返回值
描述
void
无返回值。
iv_sys_get_utc_ms
接口描述
用户自定义获取系统 UTC 时间函数，必须精确到毫秒。如果 time(NULL) 获取的是 UTC 时间，可以不用实现该回调。
uint64_t (* iv_sys_get_utc_ms)(void); 
参数说明
无
返回值
返回值
描述
uint64_t
距1970年毫秒数。
iv_sys_sync_net_time_cb
接口描述
1. 网络时间的同步接口，该接口会在上电之后首先进行时间同步并回调，以便于提早设备可用时间点。
2. 设备正常运行后每隔12小时会进行一次时间同步。由于设备的硬件时钟的差异，所以同步的时间和当前设备的时间可能不一致，需要用户根据实际需求决定是否要进行跳变的同步。
void (* iv_sys_sync_net_time_cb)(uint64_t net_time_ms); 
参数说明
参数名称
类型
描述
输入/输出
net_time_ms
uint64_t
网络时间（utc+0 ms）。
输入
返回值
返回值
描述
void
无返回值
iv_sys_set_timezone
接口描述
设置设备所运行的时区，如果设备时区设置发生变化，需要调用此函数刷新 SDK 时区。
void iv_sys_set_timezone(float fTimezone); 
参数说明
参数名称
类型
描述
输入/输出
fTimezone
float
时区（取值为标准时区值，-11 - 14）。
输入
返回值
返回值
描述
void
无返回值。
iv_sys_get_tid
接口描述
获取设备 Tid。
const char* iv_sys_get_tid(void);
参数说明
无
返回值
返回值
描述
const char*
以'\\0'结尾的 tid 字符串。
iv_sys_set_net_interface
接口描述
设置设备当前选择使用的网络接口名。
int iv_sys_set_net_interface(char* net_name);
参数说明
参数名称
类型
描述
输入/输出
net_name
char*
网络接口名（eg:"eth0"）
输入
返回值
返回值
描述
IV_ERR_NONE
无错误。
IV_ERR_CM_PARAM_OUT_RANGE
传入网口名过长（>31）。
iv_sys_get_pid
接口描述
获取设备所属的产品 ID。
const iv_sys_device_pid_st* iv_sys_get_pid(void);
参数说明
无
返回值
返回值
描述
iv_sys_device_pid_st
包含物模型 Pid 和证书 Pid。
数据结构
SDK 系统模块提供以下数据结构：
iv_sys_init_parm_s：系统初始化参数结构体。
iv_sys_certificate_type_e：证书类型枚举。
iv_sys_device_ability_e：设备内存性能枚举。
iv_sys_firmware_version_s：固件版本结构体。
iv_sys_device_pid_st： 设备 Pid 结构体。
iv_sys_device_online_result_e：设备上线结果枚举。
iv_sys_device_bind_action_e：设备绑定通知枚举。
iv_sys_init_parm_s
接口描述
系统初始化参数结构体。
typedef struct iv_sys_init_parm_s
{
    char                        s8PubStorePath[64];
    char                        s8PubCachePath[64];
    uint32_t					u32DebugMode;
    uint32_t 					u32SupportAvChnMax;
    iv_sys_device_ability_e     eDeviceAbility;    
    iv_sys_firmware_version_s	stFirmwareVersion;
    uint32_t                    need_sync_net_time;
    uint32_t                    net_chn_ring_buff_size;
    uint32_t (* iv_sys_read_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t *pCertificateLen);
    uint32_t (* iv_sys_write_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t u32CertificateLen);
    void (* iv_sys_online_cb)(uint64_t u64NetDateTime);
    void (* iv_sys_offline_cb)(void);
    uint64_t (* iv_sys_get_utc_ms)(void);
    void (*iv_sys_sync_net_time_cb)(uint64_t net_time_ms);
}iv_sys_init_parm_s;
参数说明
成员名称
描述
取值
s8PubStorePath
可读写目录，存储重要文件，断电不会丢失。
字符串，必须设置。
s8PubCachePath
可读写目录（缓存目录），存储缓存文件，断电可以丢失。
字符串，必须设置。
u32DebugMode
已废弃，更新为 iv_cm_set_log_level 接口进行控制。
0：关闭。
1：开启。
u32SupportAvChnMax
支持音视频同时的最大通道数。
视设备的 CPU 及内存情况及用户需要而定。
eDeviceAbility
设备性能。
iv_sys_device_ability_e
stFirmwareVersion
设备固件版本号。
iv_sys_firmware_version_s
need_sync_net_time
是否需要网络时间同步（设备不具备本地实时时钟系统）。
0：不需要。
1：需要。
net_chn_ring_buff_size
网络传输缓冲区大小。
该值决定传输音视频数据时抗网络波动的能力。
建议为数据大小 × 缓存时间。不填缺省为512*1024。
iv_sys_read_certificate_cb
读证书回调函数。
必须注册。
iv_sys_write_certificate_cb
写证书回调函数。
必须注册。
iv_sys_online_cb
设备上线回调函数。
必须注册。
iv_sys_offline_cb
设备离线回调函数。
-
iv_sys_get_utc_ms
用户自定义获取系统，UTC 时间。
当 time(NULL) 提供时间并未非 UTC0 时间时需要注册，用于提供 SDK 准确的 UTC0 时间。
iv_sys_sync_net_time_cb
设备同步网络时间。
-
iv_sys_certificate_type_e
接口描述
证书类型枚举。
typedef enum
{
    IV_SYS_CERTIFICATE_TYPE_INITIAL = 0,
    IV_SYS_CERTIFICATE_TYPE_ACTIVED = 1,
    IV_SYS_CERTIFICATE_TYPE_SECERT_KEY = 2,
﻿
    IV_SYS_CERTIFICATE_TYPE_BUTT
}iv_sys_certificate_type_e;
参数说明
成员名称
描述
取值
IV_SYS_CERTIFICATE_TYPE_INITIAL
初始证书
-
IV_SYS_CERTIFICATE_TYPE_ACTIVED
激活证书
-
IV_SYS_CERTIFICATE_TYPE_SECERT_KEY
证书密钥，一个 so 文件
-
iv_sys_device_ability_e
接口描述
设备性能枚举。
typedef enum
{
    IV_SYS_DEVICE_ABILITY_POOR      = 0,
    IV_SYS_DEVICE_ABILITY_ORDINARY  = 1,
    IV_SYS_DEVICE_ABILITY_RICH      = 2,
﻿
    IV_SYS_DEVICE_ABILITY_BUTT
}iv_sys_device_ability_e;
参数说明
成员名称
描述
取值
IV_SYS_DEVICE_ABILITY_POOR
内存较少
-
IV_SYS_DEVICE_ABILITY_ORDINARY
内存一般
-
IV_SYS_DEVICE_ABILITY_RICH
内存富余
-
iv_sys_firmware_version_s
接口描述
固件版本结构体。
typedef struct iv_sys_firmware_version_s
{
    uint32_t    revision:19;
    uint32_t    minor:6;
    uint32_t    major:6;
    uint32_t    debug:1;
} iv_sys_firmware_version_s;
参数说明
成员名称
描述
取值
revision
流水号
19位
minor
主版本号
6位
major
次版本号
6位
debug
测试版本标志。
0：调试固件。
1：正式固件。
1位
iv_sys_device_pid_st
设备 pid 结构体。
typedef struct iv_sys_device_pid_st{
    char dm_pid[33]; 
    char cert_pid[33];
}iv_sys_device_pid_st;
参数说明
成员名称
描述
取值
dm_pid
1. 物模型 PID。
2. 在调用 iv_dm_init 之后才可用，之前都是"0"。
-
cert_pid
1. 证书 PID。
2. 在调用 iv_sys_init 之后才可用，之前都是"0"。
-
iv_sys_device_online_result_e
设备上线状态枚举。
说明：
该状态属于 SDK 通知状态不可查询。
typedef enum
{
    IV_SYS_DEVICE_ONLINE_NONE          = 0,
    IV_SYS_DEVICE_ONLINE               = 1,
    IV_SYS_DEVICE_OFFLINE              = 2,
    IV_SYS_DEVICE_TOKEN_FAIL           = 3,
    IV_SYS_DEVICE_TID_INIT_FAIL        = 4,
    IV_SYS_DEVICE_TID_VALIDATE_FAIL    = 5,
    IV_SYS_DEVICE_KICK_OFF             = 6,
    IV_SYS_DEVICE_DEV_DISABLE          = 7,
    IV_SYS_DEVICE_PID_MISMATCH         = 8,
    IV_SYS_DEVICE_CERTIFY_CHECK_OK     = 9,
    IV_SYS_DEVICE_TID_CHECK_OK         = 10,
} iv_sys_device_online_result_e;
参数说明
成员名称
描述
取值
IV_SYS_DEVICE_ONLINE_NONE
正常情况，无需处理该状态。
0
IV_SYS_DEVICE_ONLINE
正常情况，设备已上线。
1
IV_SYS_DEVICE_OFFLINE
正常情况，设备已离线。
2
IV_SYS_DEVICE_TOKEN_FAIL
异常情况，设备 Token 校验失败，证书异常，设备环境异常。
3
IV_SYS_DEVICE_TID_INIT_FAIL
异常情况，Tid 初始化失败，加密密钥库不匹配或初始化失败。
4
IV_SYS_DEVICE_TID_VALIDATE_FAIL
异常情况，证书和加密密钥库不匹配。
5
IV_SYS_DEVICE_KICK_OFF
异常情况，设备被踢飞。
6
IV_SYS_DEVICE_DEV_DISABLE
正常情况，设备被禁用。
7
IV_SYS_DEVICE_PID_MISMATCH
异常情况，物模型和证书不匹配，不属于同一产品。
8
IV_SYS_DEVICE_CERTIFY_CHECK_OK
正常情况，证书校验成功。
9
IV_SYS_DEVICE_TID_CHECK_OK
正常情况，Tid 校验成功。
10
iv_sys_device_bind_action_e
设备被绑定、解绑的操作类型枚举。
typedef enum iv_sys_device_bind_action
{
    IV_SYS_DEIVCE_BIND_NONE      = 0,
    IV_SYS_DEIVCE_BIND_OWNER     = 1,
    IV_SYS_DEIVCE_UNBIND_OWNER   = 2,
} iv_sys_device_bind_action_e;
参数说明
成员名称
描述
取值
IV_SYS_DEIVCE_BIND_NONE
设备处于无绑定动作发生的状态，无需处理该状态。
0
IV_SYS_DEIVCE_BIND_OWNER
设备被主人绑定的操作。
1
IV_SYS_DEIVCE_UNBIND_OWNER
设备被主人解绑的操作。
2
示例代码
1. 系统初始化，设置时区
iv_sys_set_net_interface("eth0");
    iv_err_code_e eErrCode = 0;
    iv_sys_init_parm_s stSysInitParameters;	
    char s8FirmwareVersion[32] = {0};
    memset(&stSysInitParameters, 0, sizeof(iv_sys_init_parm_s));
    char app_version_file[256] = {0};
    FILE *fpFirmwareVersion = NULL;
    snprintf(app_version_file, sizeof(app_version_file), "%s/version", config_get_app_ver_file_path());
﻿
    /* 获取版本号 */
    fpFirmwareVersion = fopen(app_version_file, "r");
    if(fpFirmwareVersion)
    {
        fread(s8FirmwareVersion, 32, 1, fpFirmwareVersion);
        fclose(fpFirmwareVersion);
    }
    else
    {
        GDB_ERR("open version file '%s' failed!\\n", app_version_file);
        strcpy(s8FirmwareVersion, "1.0.0");
    }
    char *pVersion = NULL;
    char s8RealVersion[4][32];
    int s32VersionType = 0;
    pVersion = strtok(s8FirmwareVersion, ".");
    while(pVersion)
    {
        strcpy(s8RealVersion[s32VersionType], pVersion);
        GDB_INFO("version:%s\\n", s8RealVersion[s32VersionType]);
        s32VersionType++;
        pVersion = strtok(NULL, ".");
    }
    stSysInitParameters.stFirmwareVersion.major = atoi(s8RealVersion[0]);
    stSysInitParameters.stFirmwareVersion.minor = atoi(s8RealVersion[1]);
    stSysInitParameters.stFirmwareVersion.revision = atoi(s8RealVersion[2]);
    if(strcmp(s8RealVersion[3], "release") == 0)
    {
        stSysInitParameters.stFirmwareVersion.debug = 0;
    }
    else if(strcmp(s8RealVersion[3], "debug") == 0)
    {
        stSysInitParameters.stFirmwareVersion.debug = 1;
    }
    GDB_INFO("app version major:%d, minor:%d, revision:%d,debug:%d\\n", stSysInitParameters.stFirmwareVersion.major, stSysInitParameters.stFirmwareVersion.minor, stSysInitParameters.stFirmwareVersion.revision, stSysInitParameters.stFirmwareVersion.debug);
    strcpy(stSysInitParameters.s8PubStorePath, config_get_perm_rw_path());
    strcpy(stSysInitParameters.s8PubCachePath, config_get_temp_rw_path());
    stSysInitParameters.u32DebugMode = 1;
    stSysInitParameters.u32SupportAvChnMax = 4;
    stSysInitParameters.eDeviceAbility = IV_SYS_DEVICE_ABILITY_ORDINARY;
    stSysInitParameters.iv_sys_read_certificate_cb = sys_read_certificate;
    stSysInitParameters.iv_sys_write_certificate_cb = sys_write_certificate;
    stSysInitParameters.iv_sys_online_cb = sys_online;
    stSysInitParameters.iv_sys_offline_cb = sys_offline;
    stSysInitParameters.iv_sys_sync_net_time_cb = sys_sync_net_time;
﻿
    eErrCode = iv_sys_init(&stSysInitParameters);
    if(eErrCode < 0)
    {
        GDB_ERR("fail:%d\\n", eErrCode);
        return eErrCode;
    }
    /*北京时间+8 时区*/
    iv_sys_set_timezone(8);
2. 系统退出
iv_sys_exit();
﻿

下一篇: 产品动态

参数名称	类型	描述	输入/输出
pstInitParm	iv_sys_init_parm_s*	初始化参数。	输入

返回值	描述
IV_ERR_NONE	成功。
IV_ERR_*	失败，对应相应错误码。

返回值	描述
const char*	以'\\0'结尾的 tid 字符串。

返回值	描述
iv_sys_device_pid_st	包含物模型 Pid 和证书 Pid。

成员名称	描述	取值
s8PubStorePath	可读写目录，存储重要文件，断电不会丢失。	字符串，必须设置。
s8PubCachePath	可读写目录（缓存目录），存储缓存文件，断电可以丢失。	字符串，必须设置。
u32DebugMode	已废弃，更新为 iv_cm_set_log_level 接口进行控制。	0：关闭。 1：开启。
u32SupportAvChnMax	支持音视频同时的最大通道数。	视设备的 CPU 及内存情况及用户需要而定。
eDeviceAbility	设备性能。	iv_sys_device_ability_e
stFirmwareVersion	设备固件版本号。	iv_sys_firmware_version_s
need_sync_net_time	是否需要网络时间同步（设备不具备本地实时时钟系统）。	0：不需要。 1：需要。
net_chn_ring_buff_size	网络传输缓冲区大小。	该值决定传输音视频数据时抗网络波动的能力。建议为数据大小 × 缓存时间。不填缺省为512*1024。
iv_sys_read_certificate_cb	读证书回调函数。	必须注册。
iv_sys_write_certificate_cb	写证书回调函数。	必须注册。
iv_sys_online_cb	设备上线回调函数。	必须注册。
iv_sys_offline_cb	设备离线回调函数。	-
iv_sys_get_utc_ms	用户自定义获取系统，UTC 时间。	当 time(NULL) 提供时间并未非 UTC0 时间时需要注册，用于提供 SDK 准确的 UTC0 时间。
iv_sys_sync_net_time_cb	设备同步网络时间。	-