云存储模块.md

目录

• 1. 功能介绍
• 2. 使用流程
  • 基本推流过程
  • 事件推流过程
• 3. 接口参考
  • 接口列表
  • 接口描述
    • initCs
    • exitCs
    • destroyCsResource
    • pushCsStream
    • uploadCsBackupVideo
    • reportCsEventDirectly
    • startCsEvent
    • stopCsEvent
    • startCsEventExt
    • stopCsEventExt
    • getCsBalanceInfo
    • setCsAiProcess
    • getCsAiProcess
    • setCsTransTime
    • onStartPushStream
    • onStopPushStream
    • onEventCapturePicture
    • onEventPictureResult
    • onEventReportResult
    • onNotify
    • onGetBalance
    • onDumpFile
• 4. 数据结构
  • 数据结构列表
  • 数据结构描述
    • iv_cs_type_e
    • iv_cs_chn_e
    • iv_cs_up_bk_state_e
    • iv_cs_format_e
    • iv_cs_balance_info_s
    • iv_cs_ai_type_e
    • iv_cs_event_report_opt_e
    • iv_cs_upload_state_e
    • iv_cs_upload_slice_info_s
    • iv_cs_upload_info_s
    • iv_cs_notify_msg_type_e
    • iv_cs_notify_msg_data
    • iv_cs_event_result_info
    • iv_cs_congestion_ctrl_s
    • iv_cs_init_func_cb_s
    • iv_cs_channel_params_s
    • iv_cs_init_parm_s
• 5. 注意事项
• 6. 示例代码

---

1. 功能介绍

本模块用于将设备端的音视频数据推送并存储在云端，回看时由观看端（如APP）从云端拉取数据。

2. 使用流程

基本推流过程

getCsBalanceInfo //获取本地套餐信息(非必须)
    |
initCs
    |
onStartPushStream // 收到回调，开始推流
    |
while(1) { pushCsStream }
    |
onStopPushStream // 收到回调，停止推流
    |
exitCs

事件推流过程

getCsBalanceInfo //获取本地套餐信息(非必须)
    |
initCs
    |
startCsEvent/startCsEventExt // 用户触发事件
    |
onEventCapturePicture // SDK向用户请求获取事件截图
    |
onStartPushStream // 收到回调，开始推流
    |
while(1) { pushCsStream }
    |
stopCsEvent/stopCsEventExt  //用户停止事件
    ｜             
onStopPushStream // 收到回调，停止推流
    |
onEventPictureResult // 截图使用完毕，用户回收截图资源
    |
exitCs

3. 接口参考

接口列表

该功能模块提供以下接口

• initCs() 云存功能初始化
• exitCs() 云存功能关闭
• pushCsStream() 推送音、视频流

• uploadCsBackupVideo() 补传云存片段

• int startCsEvent()/startCsEventExt() 触发事件
• int stopCsEvent()/stopCsEventExt() 停止事件
• int reportCsEventDirectly() 触发即时事件上报
• int getCsBalanceInfo() 获取云存套餐信息
• int setCsTransTime() 设置云存的传输超时时间
• int setCsAiProcess() 设置云AI视频分析功能
• int getCsAiProcess() 获取云AI视频分析功能

用户需注册以下回调函数

• onStartPushStream() 音、视频流开始推流通知
• onStopPushStream() 音、视频流停止推流通知
• onEventCapturePicture() 获取事件截图
• onEventPictureResult() 事件截图使用完毕通知
• onEventReportResult)() 事件上传结果通知
• onNotify() 云存状态通知
• onGetBalance() 获取云存套餐信息
• onDumpFile() 获取云存上传流的数据（可选）

接口描述

initCs

功能描述
云存储模块初始化，注册相关回调，申请资源，需要模块时初始化调用。

函数原型

int iv_cs_init(iv_cs_init_parm_s *pstInitParm);

参数说明

参数名称	类型	描述	输入/输出
pstInitParm	iv_cs_init_parm_s *	云存初始化参数结构体	输入

返回值

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

exitCs

功能描述
云存储模块去初始化，释放资源。

函数原型

int iv_cs_exit(void); 

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

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

destroyCsResource

功能描述
云存资源销毁,该接口发请求至服务器清理云存储中已上传的资源，且会重置云存套餐

函数原型

int iv_cs_resource_destroy(uint32_t timeout_ms); 

参数说明

参数名称	类型	描述	输入/输出
timeout_ms	uint32_t	超时时间，单位:毫秒，建议值:5000	无

返回值

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

pushCsStream

功能描述
推送音视频流

函数原型

int iv_cs_push_stream(iv_cs_chn_e channel, iv_cm_stream_type_e eCsStreamType, void *pstCsStream); 

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
eCsStreamType	iv_cm_stream_type_e	云存推流类型（音频/视频）	输入
pstCsPack	void *	云存推流的数据(音频 iv_cm_aenc_pack_s，视频 iv_cm_venc_pack_s)	输入

返回值

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

使用说明
此接口禁止并行调用。 音频推荐使用ADTS的AAC裸流。 如使用G711u、G711a、PCM格式请在初始化时设置采样率、声道数等参数，对于这三种格式参数中 iv_cs_init_parm_s.av_fmt.u32SampleNumPerFrame 目前只支持1024采样点（双声道为2048采样点），双声道则左右声道交替存放(LRLRLRLR...)，以PCM为例

int16_t audio_data[1024]; // 单声道
int16_t audio_data[2048]; // 双声道

视频支持 H.264 或 H.265 含NALU的I帧、P帧裸流，不支持B帧，其中I帧需包含SPS、PPS等数据，部分裸数据格式如下

H264 I帧
00 00 00 01 67 (...) 00 00 00 01 68 (...) 00 00 00 01 65 (...)

H264 P帧
00 00 00 01 41 (...)

H265 I帧
00 00 00 01 40 (...) 00 00 00 01 42 (...) 00 00 00 01 44 (...) 00 00 00 01 2A (...)

H265 P帧
00 00 00 01 02 (...)

uploadCsBackupVideo

功能描述
补传云存片段

函数原型

int iv_cs_upload_backup_video(iv_cs_chn_e channel, iv_cs_up_bk_state_e state, char *file_name, uint8_t *buf, uint32_t len)

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cm_stream_type_e	通道号（由iv_cs_dump_file_cb输出）	输入
state	iv_cs_up_bk_state_e	传输状态	输入
file_name	char*	补传文件名（由iv_cs_dump_file_cb输出的，不含路径的文件名）	输入
buf	uint8_t*	补传文件片段的数据	输入
len	uint32_t	补传文件片段的大小	输入

返回值

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

使用说明
iv_cs_notify_cb 回调函数会反馈上传成功和失败的信息，可根据此信息内的时间戳查找需要补传的文件，utc_sec_a和utc_sec_b分别对应iv_cs_dump_file_cb的start_ts和end_ts
开始时 status = CS_UP_BK_START，填入补传的文件名（补传的文件名来自iv_cs_dump_file_cb，下同），buf填NULL，len填0
传输过程中 status = CS_UP_BK_RUNNING，填入补传的文件名
每间隔一定时间传入一定长度的buf，具体间隔时长与大小视网络情况而定
假设设备的上传带宽是200KB/s，正常云存上传会占用120KB/s，则调用此接口补传视频的速率不应超过80KB/s，例如可以每间隔100ms调用一次，每次传输8KB，直到补传结束
补传结束 status = CS_UP_BK_END，填入补传的文件名，buf填NULL，len填0
此接口为阻塞接口，补传过程中如果出错需重新补传
补传有时效限制，上传失败后请尽快补传，最长可以补传30分钟之内的视频
补传成功的视频、补传非sdk导出的视频、补传时限之外的视频等操作属于未定义行为
该接口目前只支持单线程调用，status状态有序按照 CS_UP_BK_START-->CS_UP_BK_RUNNING ... -->CS_UP_BK_END传入

reportCsEventDirectly

功能描述

• 用于触发一个事件并立即上报，事件编号的合法取值为1-32，事件编号的具体含义由用户定义
• 该接口可传入事件对应图片信息上传至云服务器，如无图片信息pic_addr填NULL，pic_len填0
• 函数执行成功事件及对应图片可上传成功，否则上报失败
• event_time_s填0时sdk则使用系统时间
• 未开通云存套餐的情况下可使用此接口上报只有图片的事件

函数原型

int iv_cs_event_directly_report(iv_cs_chn_e channel, int32_t event_id, const char *info,
                                uint32_t event_time_s, const uint8_t *pic_addr, uint32_t pic_len);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	事件编号	输入
info	const char *	自定义事件消息，含结束符'\0'在内不超过128字节，可选参数，不使用填NULL	输入
event_time_s	uint32_t	事件触发utc时间，单位：秒	输入
pic_addr	uint8_t *	事件对应图片地址	输入
pic_len	int32_t	事件对应图片长度	输入

返回值

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

startCsEvent

功能描述

• 用于触发一个事件，事件编号的合法取值为1-32，事件编号的具体含义由用户定义
• 用户触发事件以后，SDK调用 iv_cs_event_capture_picture_cb 向用户请求截图，同时会调用 iv_cs_push_stream_start_cb 通知用户开始推送音视频流
• 截图上传完毕后SDK调用 iv_cs_event_picture_result_cb 通知用户图片上传结果
• 需在上一事件停止后调用，且和 iv_cs_event_stop 成对调用
• 适用于事件发生在调用该函数这一刻的情况
• 可携带含结束符'\0'在内不超过128字节的自定义消息，消息内容仅限英文大小写、数字和常用符号
• 自定义消息的指针可以和 iv_cs_event_stop 不同，但消息内容必须和 iv_cs_event_stop 完全一致

函数原型

int iv_cs_event_start(iv_cs_chn_e channel, int32_t event_id, const char *info);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	事件编号	输入
info	const char *	自定义事件消息，可选参数，不使用填NULL	输入

返回值

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

stopCsEvent

功能描述

• 用于停止一个事件，事件编号的合法取值为1-32，事件编号的具体含义由用户定义
• 用户停止事件以后，SDK调用 iv_cs_push_stream_stop_cb 通知用户停止推送音视频流
• 必须调用 iv_cs_event_start 后才可调，且和 iv_cs_event_start 成对调用
• 可携带含结束符'\0'在内不超过128字节的自定义消息，消息内容仅限英文大小写、数字和常用符号
• 自定义消息的指针可以和 iv_cs_event_start 不同，但消息内容必须和 iv_cs_event_start 完全一致

函数原型

int iv_cs_event_stop(iv_cs_chn_e channel, int32_t event_id, const char *info);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	事件编号	输入
info	const char *	自定义事件消息，可选参数，不使用填NULL	输入

返回值

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

startCsEventExt

功能描述

• 用于触发一个事件，事件编号的合法取值为1-32，事件编号的具体含义由用户定义
• 用户触发事件以后，SDK调用 iv_cs_event_capture_picture_cb 向用户请求截图，同时会调用 iv_cs_push_stream_start_cb 通知用户开始推送音视频流
• 截图上传完毕后SDK调用 iv_cs_event_picture_result_cb 通知用户图片上传结果
• 适用于预录视频的场景
• 当 event_start_time_s 和 stream_start_time_s 小于 300 时，该值作为相对时间使用但不得小于0（小于零代表事件开始在未来，无意义），例如 event_start_time_s = 15 代表事件发生的时间是调用此函数前的15秒；大于 300 时作为绝对时间使用，即 UTC 时间
• event_start_time_s 和 stream_start_time_s 必须同为相对时间或同为绝对时间，不得混用
• event_start_time_s 和 stream_start_time_s 可以相同或不相同，可根据实际使用场景填写，例如 stream_start_time_s 填写 15 表示视频开始于调用此函数前的15秒，event_start_time_s 填写 0 表示事件发生于调用此函数的这一刻，这样就实现了预录视频还原完整事件经过的效果
• event_start_time_s 和 stream_start_time_s 作为绝对时间使用时，用户需尽量保证时间准确，以免云存录像时间出现太大偏差；使用过程中尽量避免向前校时，如果校时后的时间早于最后一段视频的结束时间可能导致已经上传的录像被覆盖
• 可携带含结束符'\0'在内不超过128字节的自定义消息，消息内容仅限英文大小写、数字和常用符号
• 自定义消息的指针可以和 iv_cs_event_stop_ext 不同，但消息内容必须和 iv_cs_event_stop_ext 完全一致

函数原型

int iv_cs_event_start_ext(iv_cs_chn_e channel, int32_t event_id, const char *info,
                          uint32_t event_start_time_s, uint32_t stream_start_time_s);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	事件编号	输入
info	const char *	自定义事件消息，可选参数，不使用填NULL	输入
event_start_time_s	uint32_t	事件开始的utc时间	输入
stream_start_time_s	uint32_t	事件对应视频开始的utc时间	输入

返回值

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

stopCsEventExt

功能描述

• 用于停止一个事件，事件编号的合法取值为1-32，事件编号的具体含义由用户定义
• 用户停止事件以后，SDK调用 iv_cs_push_stream_stop_cb 通知用户停止推送音视频流
• 必须调用 iv_cs_event_start_ext 后才可调，且和iv_cs_event_start_ext成对调用
• 当 event_stop_time_s 或 stream_stop_time_s 小于 300 时，该值作为相对时间使用但不得小于0（小于零代表事件结束在未来，无意义），例如 event_stop_time_s = 15 代表事件结束的时间是调用此函数前的15秒；大于 300 时作为绝对时间使用，即 UTC 时间
• event_stop_time_s 和 stream_stop_time_s 必须同为相对时间或同为绝对时间，不得混用
• event_stop_time_s 和 stream_stop_time_s 作为绝对时间使用时，用户需尽量保证时间准确，以免云存录像时间出现太大偏差；使用过程中尽量避免向前校时，如果校时后的时间早于最后一段视频的结束时间可能导致已经上传的录像被覆盖
• 可携带含结束符'\0'在内不超过128字节的自定义消息，消息内容仅限英文大小写、数字和常用符号
• 自定义消息的指针可以和 iv_cs_event_start_ext 不同，但消息内容必须和 iv_cs_event_start_ext 完全一致

函数原型

int iv_cs_event_stop_ext(iv_cs_chn_e channel, int32_t event_id, const char *info,
                         uint32_t event_stop_time_s, uint32_t stream_stop_time_s);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	事件编号	输入
info	const char *	自定义事件消息，可选参数，不使用填NULL	输入
event_stop_time_s	uint32_t	事件结束的utc时间	输入
stream_stop_time_s	uint32_t	事件对应视频结束的utc时间	输入

返回值

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

getCsBalanceInfo

功能描述

• 用于获取当前设备的云存的套餐信息
• 当 timeout_s大于0时，该接口为阻塞获取信息，直接从后台获取最新套餐信息，失败返回错误码IV_ERR_CS_QUERY_SERVICE_TIMEOUT，成功返回IV_ERR_NONE和套餐信息
• 当 timeout_s等于0时，该接口为非阻塞接口，直接返回SDK内的套餐缓存信息
• 当云存的套餐在后台发生变化后，正常情况下会及时更新到设备并缓存再SDK内，通过本接口直接查询SDK内缓存套餐信息效率更高
• 接口可在设备上线后云存SDK未初始化前进行调用来获取套餐信息，云存SDK未初始化时采用轮询方式调用该接口，建议只在第一次调用时采用阻塞方式，后续的调用采用非阻塞方式，否则会引起带宽资源浪费

函数原型

int iv_cs_get_balance_info(iv_cs_chn_e channel, iv_cs_balance_info_s *pstBalanceInfo, uint32_t timeout_s)

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
pstBalanceInfo	iv_cs_balance_info_s	云存套餐信息	输出
timeout_s	uint32_t	接口获取超时时间(单位:秒)	输入

返回值

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

setCsAiProcess

功能描述

• 设置需要进行 AI 分析的事件 ID 以及 AI分析的类型
• 可以在云存初始化之后、云存退出前任意时刻调用，如需长期使能AI，建议在云存初始化后进行设置，在云存退出前关闭，减少在事件触发时频繁开关

函数原型

int iv_cs_set_ai_process(iv_cs_chn_e channel, int32_t event_id, iv_cs_ai_type_e ai_type, void *args);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	需要进行AI分析的事件ID	输入
ai_type	iv_cs_ai_type_e	需要进行AI分析的类型	输入
args	void *	用户参数，暂未使用，填NULL	输入

返回值

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

getCsAiProcess

功能描述
获取某个事件的AI分析类型

函数原型

int iv_cs_get_ai_process(iv_cs_chn_e channel, int32_t event_id, iv_cs_ai_type_e *ai_type, void *args);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入
event_id	int32_t	需要读取的事件ID	输入
ai_type	iv_cs_ai_type_e *	事件的AI分析类型	输入
args	void *	用户参数，暂未使用，填NULL	输入

返回值

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

setCsTransTime

功能描述
分别设置云存传输的上传和接收最大超时时间，单位毫秒，不能设置为0;

函数原型

int iv_cs_set_trans_time(uint32_t upload_timeout_ms, uint32_t reply_timeout_ms)

参数说明

参数名称	类型	描述	输入/输出
upload_timeout_ms	uint32_t	上传最大超时时间，单位毫秒	输入
reply_timeout_ms	uint32_t	接口最大超时时间，单位毫秒	输入

返回值

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

onStartPushStream

功能描述
开始推流回调，事件触发后、云存套餐开通后等情况会触发此回调，收到此回调后方可开始推流。

函数原型

int (*iv_cs_push_stream_stop_cb)(iv_cs_chn_e channel);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入

返回值

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

onStopPushStream

功能描述
停止推流回调，事件结束、云存服务到期等情况会触发此回调，收到此回调后停止推流。

函数原型

int (*iv_cs_push_stream_start_cb)(iv_cs_chn_e channel);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输入

返回值

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

onEventCapturePicture

功能描述
抓图回调，建议非阻塞使用，仅支持jpg格式，返回时提供图片指针和大小，如果不需抓图请填NULL和0

函数原型

int (*iv_cs_event_capture_picture_cb)(iv_cs_chn_e channel, int32_t event_id, uint8_t **pic, int32_t *size);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输出
event_id	int32_t	用户触发的事件id，根据不同id可以上传对应事件的图片	输出
pic	uint8_t **	指向保存截图的内存	输出
size	int32_t *	指向截图的大小	输出

返回值

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

onEventPictureResult

功能描述
上传图片结束回调，并通知上传结果 每张抓图都会回调一次，在收到对应图片回调前不得回收图片资源，以免SDK上传图片失败

函数原型

int (*iv_cs_event_picture_result_cb)(iv_cs_chn_e channel, uint8_t **pic, iv_err_code_e err_code);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输出
pic	uint8_t **	指向保存截图的内存，与 iv_cs_event_capture_picture_cb 的入参对应	输出
err_code	iv_err_code_e	上传图片的结果	输出

返回值

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

onEventReportResult

功能描述
用户事件上报结果回调，用户结束事件后事件上报的结果通过该回调通知，成功说明该事件对应的视频、图片已按照预期上传 且该事件也已经上报成功

函数原型

int (*iv_cs_event_report_result_cb)(iv_cs_chn_e channel, iv_cs_event_result_info *pst_result_info);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输出
pst_result_info	iv_cs_event_result_info *	指向事件上报结果的信息	输出

返回值

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

onNotify

功能描述
云存消息通知回调，目前包括云存视频分段的上传情况通知、内部上传连接情况通知、内部发送缓存水位告警通知消息等 notify_msg_type 为 IV_CS_AV_UPLOAD_STATE_MSG 时，pst_notify_data 使用联合体成员 iv_cs_upload_info_s notify_msg_type 为其余消息时，pst_notify_data 为 NULL

函数原型

int (*iv_cs_notify_cb)(iv_cs_chn_e channel, iv_cs_notify_msg_type_e notify_msg_type,
                       iv_cs_notify_msg_data *pst_notify_data);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输出
notify_msg_type	iv_cs_notify_msg_type_e	云存通知消息类型	输出
pst_notify_data	iv_cs_notify_msg_data*	云存通知消息数据	输出

返回值

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

onGetBalance

功能描述
针对不支持mqtt通信时，获取云存套餐信息回调 仅用于低功耗一个三元组场景下，从芯片(WIFI侧)收到云存套餐变更后，sdk通过该回调获取最新套餐信息 该接口会频繁调用，建议缓存处理等待（WIFI测）mqtt主动下发，禁止使用mqtt实时同步套餐 禁止回调内调用iv_cs_get_balance_info

函数原型

void (*iv_cs_get_balance_cb)(iv_cs_chn_e channel, int8_t *is_vaild, iv_cs_balance_info_s *pst_balance_info, int32_t timeout_ms);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	云存通道ID	输出
is_vaild	int8_t*	云存套餐是否有效	输出
pst_balance_info	iv_cs_balance_info_s*	云存套餐信息	输出
timeout_ms	int32_t	超时时间，0为非阻塞	输出

返回值

返回值	描述
无	无

onDumpFile

功能描述
此回调函数会实时导出所有云存录像的数据，用户可保存数据，配合iv_cs_upload_backup_video实现补传
导出开始 status = CS_UP_BK_START，start_ts为开始时间戳，end_ts为0, file_name为NULL，buf为NULL，len为0
导出过程中 status = CS_UP_BK_RUNNING，start_ts为开始时间戳，end_ts为0, file_name为NULL，buf为导出的数据，len为导出的数据长度
导出结束 status = CS_UP_BK_END，start_ts为开始时间戳，end_ts为结速时间戳，file_name为保存文件名，buf为NULL，len为0
导出的视频片段长度约为10秒，导出的文件大小略大于10秒内推送到iv_cs_push_stream内的数据量，回调函数中请勿阻塞

函数原型

int (*iv_cs_dump_file_cb)(iv_cs_chn_e channel, iv_cs_up_bk_state_e state, uint64_t start_ts, uint64_t end_ts, char *file_name, uint8_t *buf, uint32_t len);

参数说明

参数名称	类型	描述	输入/输出
channel	iv_cs_chn_e	通道号	输入
state	iv_cs_up_bk_state_e	传输状态	输入
start_ts	uint64_t	开始时间戳，单位毫秒	输入
end_ts	uint64_t	结束时间戳，单位毫秒	输入
file_name	char*	导出的文件名	输入
buf	uint8_t*	补传文件片段的数据	输入
len	uint32_t	补传文件片段的大小	输入

返回值

返回值	描述
非负数	保存的数据的大小

4. 数据结构

数据结构列表

云存模块涉及以下数据结构

• iv_cm_* 请参考音视频结构公共模块

• iv_cs_type_e 云存套餐类型枚举
• iv_cs_chn_e 云存通道枚举
• iv_cs_balance_info_s 云存套餐状态结构体
• iv_cs_ai_type_e 云AI分析的类型枚举
• iv_cs_event_report_opt_e 事件云存上传类型枚举
• iv_cs_upload_state_e 云存上传状态枚举
• iv_cs_upload_slice_info_s 云存某段视频上传状态结构体
• iv_cs_upload_info_s 云存视频上传状态结构体
• iv_cs_notify_msg_type_e 云存回调消息类型
• iv_cs_notify_msg_data 云存回调消息联合体
• iv_cs_event_result_info 云存事件上传结果结构体
• iv_cs_congestion_ctrl_s 云存水位控制结构体
• iv_cs_init_parm_s 云存模块初始化参数结构体

数据结构描述

iv_cs_type_e

功能描述
云存套餐类型

结构原型

typedef enum
{
    CS_TYPE_NONE       = 0,
    CS_TYPE_FULL_TIME  = 1,
    CS_TYPE_EVENT      = 2,
    CS_TYPE_FREE_TRIAL = 3,
} iv_cs_type_e;

参数说明

成员名称	描述	取值
CS_TYPE_NONE	无套餐	0
CS_TYPE_FULL_TIME	全时套餐	1
CS_TYPE_EVENT	事件套餐	2
CS_TYPE_FREE_TRIAL	试用套餐	3

iv_cs_chn_e

功能描述
云存通道枚举

结构原型

typedef enum
{
    CS_SINGLE_CH = 0,
    CS_MULTI_CH1 = 1,
    CS_MULTI_CH2 = 2,
    CS_CH_NUM    = 3,
} iv_cs_chn_e;

参数说明

成员名称	描述	取值
CS_SINGLE_CH	单通道	0
CS_MULTI_CH1	多通道channel 1	1
CS_MULTI_CH2	多通道channel 2	2
CS_CH_NUM	最大通道数	3

iv_cs_up_bk_state_e

功能描述
云存补传状态

结构原型

typedef enum
{
    CS_UP_BK_START   = 0,
    CS_UP_BK_RUNNING = 1,
    CS_UP_BK_END     = 2,
    CS_UP_BK_BUTT    = 3,
} iv_cs_up_bk_state_e;

参数说明

成员名称	描述	取值
CS_UP_BK_START	开始	iv_cs_up_bk_state_e
CS_UP_BK_RUNNING	补传中	iv_cs_up_bk_state_e
CS_UP_BK_END	结束	iv_cs_up_bk_state_e
CS_UP_BK_BUTT	-	-

iv_cs_format_e

功能描述
云存封装格式

结构原型

typedef enum
{
    IV_CS_FORMAT_TS = 0,
    IV_CS_FORMAT_FMP4 = 1,
} iv_cs_format_e;

参数说明

成员名称	描述	取值
IV_CS_FORMAT_TS	ts格式封装	0
IV_CS_FORMAT_FMP4	fmp4格式封装	1

iv_cs_balance_info_s

功能描述
云存套餐结构体 free_trial_remaining_sec 仅当 cs_type 为 CS_TYPE_FREE_TRIAL 时有效，其他情况无效

结构原型

typedef struct iv_cs_balance_s {
    int cs_switch;
    int cs_days;
    iv_cs_type_e cs_type;
    int free_trial_remaining_sec;
} iv_cs_balance_info_s;

参数说明

成员名称	描述	取值
cs_switch	云存开关	int
cs_days	云存回看天数	int
cs_type	云存套餐类型	iv_cs_type_e
free_trial_remaining_sec	试用套餐剩余可用时长，单位秒	int

iv_cs_ai_type_e

功能描述
云AI类型

结构原型

typedef enum
{
    CS_AI_TYPE_CLOSE       = (uint32_t)0,
    CS_AI_TYPE_FALL_DETECT = (uint32_t)(1 << 0),
} iv_cs_ai_type_e;

参数说明

成员名称	描述	取值
CS_AI_TYPE_CLOSE	关闭云AI	(uint32_t)0
CS_AI_TYPE_FALL_DETECT	老人跌倒检测云AI	(uint32_t)(1 << 0)

iv_cs_event_report_opt_e

功能描述
事件云存上传类型枚举，用于告知 SDK 所有事件按视频事件处理或按图片事件处理，默认为0。 设置为 CS_EVENT_VIDEO_REQ 时，至少成功上传一段视频 SDK 才认为这是一个完整事件 设置为 CS_EVENT_PIC_REQ 时，成功上传截图后 SDK 才认为这是一个完整事件 设置为 CS_EVENT_VIDEO_OR_PIC_REQ 时，成功上传一段视频或成功上传截图 SDK 都认为这是一个完整事件 例如：假设用户要求所有事件必须有视频，建议设置为 CS_EVENT_VIDEO_REQ；假设用户只需上传事件截图不需上传视频，建议设置为 CS_EVENT_PIC_REQ

结构原型

typedef enum cs_event_upload_options
{
    CS_EVENT_VIDEO_REQ = 0,
    CS_EVENT_PIC_REQ = 1,
    CS_EVENT_VIDEO_OR_PIC_REQ = 2,
} iv_cs_event_report_opt_e;

参数说明

成员名称	描述	取值
CS_EVENT_VIDEO_REQ	成功上传视频，图片可选上传	0
CS_EVENT_PIC_REQ	成功上传截图，视频可选上传	1
CS_EVENT_VIDEO_OR_PIC_REQ	成功上传视频或图片	2

iv_cs_upload_state_e

功能描述
视频是否上传成功

结构原型

typedef enum
{
    IV_CS_UPLOAD_OK  = 0,
    IV_CS_UPLOAD_ERR = 1,
} iv_cs_upload_state_e;

参数说明

成员名称	描述	取值
IV_CS_UPLOAD_OK	上传成功	0
IV_CS_UPLOAD_ERR	上传失败	1

iv_cs_upload_slice_info_s

功能描述
通知用户某段视频的上传状态 用户可根据其中的UTC时间、PTS、帧序号等信息得知视频上传的状态 此结构体内记录的信息均为视频帧 一般而言只有 upload_size == total_size 且 state == IV_CS_UPLOAD_OK 才认为视频上传完全正常

结构原型

typedef struct {
    uint64_t utc_sec_a;
    uint64_t utc_sec_b;
    uint64_t pts_ms_a;
    uint64_t pts_ms_b;
    uint32_t frame_seq_a;
    uint32_t frame_seq_b;
    uint32_t upload_size;
    uint32_t total_size;
    iv_cs_upload_state_e state;
} iv_cs_upload_slice_info_s;

参数说明

成员名称	描述	取值
utc_sec_a	本段视频开始的UTC时间（SDK内部生成）	uint64_t
utc_sec_b	本段视频结束的UTC时间（SDK内部生成）	uint64_t
pts_ms_a	本段视频第一帧的PTS（来自 iv_cs_push_stream）	uint64_t
pts_ms_b	本段视频最后一帧的PTS（来自 iv_cs_push_stream）	uint64_t
frame_seq_a	本段视频第一帧的序号（来自 iv_cs_push_stream）	uint32_t
frame_seq_b	本段视频最后一帧的序号（来自 iv_cs_push_stream）	uint32_t
upload_size	本段视频上传成功的大小（估算值）	uint32_t
total_size	本段视频总大小（精确值）	uint32_t
state	本段视频的上传状态（成功/失败）	iv_cs_upload_state_e

iv_cs_upload_info_s

功能描述
通知用户视频的上传状态，由若干 iv_cs_upload_slice_info_s 组成

结构原型

typedef struct {
    iv_cs_upload_slice_info_s slice_info[MAX_UPLOAD_INFO_NUM];
    int32_t num;
} iv_cs_upload_info_s;

参数说明

成员名称	描述	取值
slice_info	某段视频的上传状态	iv_cs_upload_slice_info_s
num	slice_info 的数量	int32_t

iv_cs_notify_msg_type_e

功能描述
云存回调消息类型

结构原型

typedef enum cs_notify_type
{
    IV_CS_AV_UPLOAD_CONNECT_FAIL = 0,
    IV_CS_AV_UPLOAD_CONNECT_RECOVER = 1,
    IV_CS_AV_UPLOAD_STATE_MSG = 2,
    IV_CS_AV_UPLOAD_WATERMARK_LOW = 3,
    IV_CS_AV_UPLOAD_WATERMARK_WARN = 4,
    IV_CS_AV_UPLOAD_WATERMARK_HIGH = 5,
    IV_CS_COS_SERVICE_WRONG = 6,
    IV_CS_MSG_BUTT
} iv_cs_notify_msg_type_e;

参数说明

成员名称	描述	取值
IV_CS_AV_UPLOAD_CONNECT_FAIL	云存服务器连接失败	0
IV_CS_AV_UPLOAD_CONNECT_RECOVER	云存服务器连接恢复	1
IV_CS_AV_UPLOAD_STATE_MSG	云存上传状态消息	2
IV_CS_AV_UPLOAD_WATERMARK_LOW	云存低水位告警	3
IV_CS_AV_UPLOAD_WATERMARK_WARN	云存中水位告警	4
IV_CS_AV_UPLOAD_WATERMARK_HIGH	云存高水位告警	5
IV_CS_COS_SERVICE_WRONG	云存服务不可用	6
IV_CS_MSG_BUTT	-	-

iv_cs_notify_msg_data

功能描述
iv_cs_notify_cb 回调携带的消息联合体

结构原型

typedef union {
    iv_cs_upload_info_s *av_result_info;
} iv_cs_notify_msg_data;

参数说明

成员名称	描述	取值
av_result_info	视频上传的结果	iv_cs_upload_info_s

iv_cs_event_result_info

功能描述
事件的上传结果

结构原型

typedef struct {
    int32_t result_code;
    int32_t event_id;
    uint32_t start_time_s;
    uint32_t end_time_s;
} iv_cs_event_result_info;

参数说明

成员名称	描述	取值
result_code	上报结果	0:失败，1:成功
event_id	事件序号	1到32
start_time_s	事件开始时间，单位秒	UTC时间戳
end_time_s	事件结束时间，单位秒	UTC时间戳

iv_cs_congestion_ctrl_s

功能描述
设置云存缓存水位告警相关参数

结构原型

typedef struct {
    size_t low_mark;
    size_t warn_mark;
    size_t high_mark;
    int8_t enable;
} iv_cs_congestion_ctrl_s;

参数说明

成员名称	描述	取值
low_mark	设置触发告警的低水位值，单位字节	不大于 u32MaxGopSize，建议u32MaxGopSize的10%左右
warn_mark	设置触发告警的中水位值，单位字节	不大于 u32MaxGopSize，建议u32MaxGopSize的40%左右
high_mark	设置触发告警的高水位值，单位字节	不大于 u32MaxGopSize，建议不大于u32MaxGopSize的80%
enable	设置是否开启水位值告警功能	0:否，1:是

iv_cs_init_func_cb_s

功能描述
云存初始化回调函数结构体

结构原型

typedef struct iv_cs_init_func_cb {
    int (*iv_cs_push_stream_start_cb)(iv_cs_chn_e channel);
    int (*iv_cs_push_stream_stop_cb)(iv_cs_chn_e channel);
    void (*iv_cs_ai_service_notify_cb)(iv_cs_chn_e channel, unsigned int ai_server_type, unsigned long long utc_expire);
    int (*iv_cs_event_capture_picture_cb)(iv_cs_chn_e channel, int32_t event_id, uint8_t **pic, int32_t *size);
    int (*iv_cs_event_picture_result_cb)(iv_cs_chn_e channel, uint8_t **pic, int32_t err_code);
    int (*iv_cs_event_report_result_cb)(iv_cs_chn_e channel, iv_cs_event_result_info *pst_result_info);
    int (*iv_cs_notify_cb)(iv_cs_chn_e channel, iv_cs_notify_msg_type_e notify_msg_type,
                           iv_cs_notify_msg_data *pst_notify_data);
    void (*iv_cs_get_balance_cb)(iv_cs_chn_e channel, int8_t *is_vaild, iv_cs_balance_info_s *pst_balance_info,int32_t timeout_ms);
    int (*iv_cs_dump_file_cb)(iv_cs_chn_e channel, iv_cs_up_bk_state_e state, uint64_t start_ts,
                              uint64_t end_ts, char *file_name, uint8_t *buf, uint32_t len);
} iv_cs_init_func_cb_s;

参数说明

成员名称	描述	取值
iv_cs_push_stream_start_cb	开始推流回调（详细说明见上文）	无
iv_cs_push_stream_stop_cb	停止推流回调（详细说明见上文）	无
iv_cs_ai_service_notify_cb	云AI服务状态回调（暂未使用）	NULL
iv_cs_event_capture_picture_cb	获取事件截图回调（详细说明见上文）	无
iv_cs_event_picture_result_cb	图片上传结果回调（详细说明见上文）	无
iv_cs_event_report_result_cb	事件上报结果回调（详细说明见上文）	无
iv_cs_notify_cb	云存模块消息通知回调（详细说明见上文）	无
iv_cs_get_balance_cb	获取云存套餐信息回调（详细说明见上文）	无
iv_cs_dump_file_cb	保存云存的上传数据流回调（详细说明见上文）

iv_cs_channel_params_s

功能描述
云存通道参数结构体

结构原型

typedef struct iv_cs_channel_params {
    iv_cs_chn_e channel_id;
    uint32_t u32MaxGopSize;
    iv_cs_congestion_ctrl_s congestion_cfg;
    iv_cm_av_data_info_s av_fmt;
    iv_cs_format_e cs_fmt;
    iv_cs_event_report_opt_e event_report_opt;
} iv_cs_channel_params_s;

参数说明

成员名称	描述	取值
channel_id	通道ID号	uint8_t
u32MaxGopSize	云存缓存大小，单位字节，取值为4KB的整数倍	uint32_t
congestion_cfg	视频上传拥塞控制信息	iv_cs_congestion_ctrl_s
av_fmt	云存音视频格式（如果云存视频采用动态帧率，其中的 u32Framerate 请填0）	iv_cm_av_data_info_s
cs_fmt	云存封装音视频格式	iv_cs_format_e
event_report_opt	事件上报选项设置	iv_cs_event_report_opt

iv_cs_init_parm_s

功能描述
云存模块初始化参数结构体

结构原型

typedef struct iv_cs_init_parm_s {
    int channel_num;
    iv_cs_init_func_cb_s func_cb;
    iv_cs_channel_params_s *ch_params;
} iv_cs_init_parm_s;

参数说明

成员名称	描述	取值
channel_num	云存开启通道数，最大通道数参考CS_CH_NUM	uint32_t
func_cb	云存回调结构	iv_cs_init_func_cb_s
ch_params	云存通道参数数组指针	iv_cs_channel_params_s

5. 注意事项

1. 云存开始推流送入的第一帧尽量保证为IDR帧，否则回放时可能导致花屏、解码失败等问题
2. 云存可能因网络波动上传失败，使用过程请尽量保持网络状况良好
3. u32MaxGopSize 取值推荐至少能保存一个GOP的视频和对应的音频，假设帧率为20fps，GOP为80帧，经统计4秒的视频数据约700KB，音频约60KB，则 u32MaxGopSize 可以取 800KB
4. u32MaxGopSize 如果设备内存紧张可以适当减小，如减小至原来的80%（上述为例即640KB），但不得小于一个I帧的大小，取值过小会导致云存上传更难以承受网络波动
5. 用户可以在未收到 iv_cs_push_stream_stop_cb 回调的情况下主动停止推送云存录像，SDK超过120秒未收到音视频数据会暂停云存录像
6. 云存使用过程中禁止修改音视频格式，如格式发生变化，请调用 iv_cs_exit 关闭云存，再调用 iv_cs_init 重新初始化云存并设置新的音视频格式
7. 云存功能内存开销计算：
   • 输入aac格式音频：内存开销 = u32MaxGopSize + 100KB(SDK内部数据)
   • 输入其他格式音频：内存开销 = u32MaxGopSize + 120KB(单声道) 或 160KB(双声道) + 100KB(SDK内部数据)
8. 事件云存触发建议事件至少持续3s及以上以保证视频片段、图片可及时上传，不会发生丢弃；否则可能会发生视频、图片上传失败，只上报事件触发消息等类似情况
9. 单个事件持续时间建议不要超过1小时，尽量控制在10分钟以内，如果持续时间确实很长建议进行分割
10. 事件云存支持并行事件，同一时刻允许触发多个不同事件，但不能触发多个相同事件
11. 事件云存支持预录视频，网络良好的情况允许预录视频快速上传来追赶实时视频
12. 并行事件只有第一个触发的事件支持预录视频，后续并行事件调用 iv_cs_event_start_ext()，stream_start_time_s 请填0或当前UTC时间；或直接调用 iv_cs_event_start()
13. 如果没有套餐，全时云存不会触发推流通知, 此时推流也会返回错误码IV_ERR_CS_APPLY_NO_SERVICE;需要用户定时检查套餐情况:

• 当全时云存套餐生效时，会触发开始推流通知,当无效时，会触发停止推流通知;
• 当事件云存套餐生效时，不会有通知，但此时调用事件云存的相关接口可以正常工作;

14. 事件支持无图片事件，当事件无图片时sdk不会调用iv_cs_event_picture_result_cb释放图片资源;
15. 事件云存强烈建议不要上传未来的视频，SDK可以接受小幅度的时钟误差（建议正负1分钟以内）。系统时钟快于现实时间这种情况在使用中要特别注意，以免导致视频被覆盖。假设这样一个场景：现实时间为 09:00:00，设备端的系统时钟为09:00:40，此时触发了一个10秒的事件，并上传视频，即视频的时间为 09:00:40-09:00:50，之后设备开始校时，将时间修改为 09:00:10，在 09:00:30 触发了一个30秒的事件，并上传视频，即视频的时间为 09:00:30-09:01:00，此时第二个事件的视频会覆盖第一个事件的视频。
16. 云存消息通知回调 iv_cs_notify_cb 需要支持重入
17. iOS微信小程序不支持ts格式封装的H.265云存视频，如需使用iOS微信小程序回看H.265的云存视频请将初始化参数中的cs_fmt设置为fmp4格式
18. 当前套餐为试用套餐时，若正在触发事件并上传云存视频，使用 iv_cs_get_balance_info 接口查到的 free_trial_remaining_sec 时间不准确。无云存上传，或 iv_cs_event_report_result_cb 回调函数调用后可保证 free_trial_remaining_sec 时间准确。

6. 示例代码

// 云存推流
while (run_flag)
{
    // 调用者主动推流，由调用者保证推送音视频帧的顺序与间隔，否则可能造成音视频不同步
    if(compare_time_stamp(frame_count_audio, audio_time_base, frame_count_video, video_time_base) <= 0)
    {
        frame_count_audio += 1;
        get_aac_frame(audio_frame_buf, &audio_len);
        audio_pack.pu8Addr = audio_frame_buf;
        audio_pack.u32Len = audio_len;
        audio_pack.u64TimeStamp = (uint64_t)(frame_count_a * 1024 / 48.0);
        audio_pack.u32Seq = frame_count_a;
        iv_cs_push_stream(IV_CM_STREAM_TYPE_AUDIO, &audio_pack);
    }
    else
    {
        frame_count_video += 1;
        get_video_frame_h264(video_frame_buf, &video_len, &frame_type);
        video_pack.pu8Addr = video_frame_buf;
        video_pack.u32Len = video_len;
        video_pack.eFrameType = frame_type;
        video_pack.u64PTS = (uint64_t)(frame_count_v * 1000 / 25.0);
        video_pack.u32Seq = frame_count_v;
        iv_cs_push_stream(IV_CM_STREAM_TYPE_VIDEO, &video_pack);
    }
    sleep_ms(10);
}

详细例程请参考 samples\samples\cloud_storage\cloud_storage.c 及 samples\samples\ 目录内的其他代码