C API 说明
C SDK 面向设备录像上传，公共头文件为 ticloudstorage.h；运行时扩展配置位于 ticloudstorage_ext.h。所有时间戳使用 UTC Unix 毫秒。
返回 ID 的函数成功时返回正数，失败时返回负数错误码；其他函数成功返回 TICLOUDSTORAGE_OK。
接入头文件、二进制库和设备身份见 C SDK 接入。
调用顺序
结构体字段、返回值处理和线程同步见上传录像。
// 每个进程按一次 TiCloudStorage 生命周期初始化。
struct TiCloudStorageOptions options = TICLOUDSTORAGE_OPTIONS_INITIALIZER;
TiCloudStorageInit(&options);
// 一条 Service 对应一条独立媒体时间线。
struct TiCloudStorageServiceOptions service_options =
TICLOUDSTORAGE_SERVICE_OPTIONS_INITIALIZER;
service_options.device_secret_key = device_secret_key;
service_options.on_token_will_expire = on_token_will_expire;
service_options.on_token_expired = on_token_expired;
int service_id = TiCloudStorageServiceCreate(device_id, &service_options);
TiCloudStorageServiceUpdateToken(service_id, device_access_token);
TiCloudStorageServiceStart(service_id);
// 提交逻辑上传请求。正数 upload_id 只表示请求已经受理。
struct TiCloudStorageUploadRequestOptions request =
TICLOUDSTORAGE_UPLOAD_REQUEST_OPTIONS_INITIALIZER;
request.start_time_ms = TICLOUDSTORAGE_TIME_EARLIEST;
request.duration_ms = 0;
request.on_progress = on_upload_progress;
request.on_result = on_upload_result;
int upload_id = TiCloudStorageUploadRequest(service_id, &request);
// 采集线程持续写入完整编码帧；成功只表示帧进入本地队列。
TiCloudStorageQueueWriteFrame(service_id, &frame_info, frame_data);
// duration_ms 为 0 时，设置右开的结束时间，再等待唯一的 on_result。
TiCloudStorageUploadSetEnd(service_id, upload_id, end_time_ms);
// on_result 返回且送帧线程停止后，再释放 Service 和进程级资源。
TiCloudStorageServiceStop(service_id);
TiCloudStorageServiceDestroy(service_id);
TiCloudStorageUninit();先停止全部送帧线程，并等待需要保留的上传请求返回 on_result，再停止 Service。TiCloudStorageServiceStop() 会中止任务，不会代替应用排空上传。
错误码
C SDK 失败时返回负数。当前取值从 -50000 起，按类别分段。业务判断比较这些常量，不要解析 TiCloudStorageGetErrorString() 的文本。
| 值 | 常量 | 含义 |
|---|---|---|
| 0 | TICLOUDSTORAGE_OK | 成功 |
| -50001 | TICLOUDSTORAGE_E_INVALID_ARGUMENT | 参数不合法 |
| -50002 | TICLOUDSTORAGE_E_NOT_INITIALIZED | 尚未初始化，或已经反初始化 |
| -50003 | TICLOUDSTORAGE_E_ALREADY_INITIALIZED | 已经初始化，不能重复初始化 |
| -50004 | TICLOUDSTORAGE_E_NO_MEMORY | 内存不足 |
| -50005 | TICLOUDSTORAGE_E_INTERNAL | SDK 内部错误 |
| -50099 | TICLOUDSTORAGE_E_NOT_IMPLEMENTED | 当前版本未实现该能力 |
| -50100 | TICLOUDSTORAGE_E_SERVICE_NOT_FOUND | Service 不存在 |
| -50101 | TICLOUDSTORAGE_E_SERVICE_INVALID_STATE | Service 当前状态不允许该操作 |
| -50102 | TICLOUDSTORAGE_E_SERVICE_ID_EXHAUSTED | 无法再分配 Service ID |
| -50103 | TICLOUDSTORAGE_E_SERVICES_ACTIVE | 仍有 Service，不能反初始化 |
| -50200 | TICLOUDSTORAGE_E_UNSUPPORTED_MEDIA | 媒体编号不在音频或视频预留范围 |
| -50201 | TICLOUDSTORAGE_E_TIMESTAMP_OUT_OF_ORDER | 同一通道、同一媒体类型时间戳倒退 |
| -50202 | TICLOUDSTORAGE_E_QUEUE_FULL | 本地环形队列没有可用空间 |
| -50300 | TICLOUDSTORAGE_E_UPLOAD_NOT_FOUND | 上传请求不存在 |
| -50301 | TICLOUDSTORAGE_E_UPLOAD_FINISHED | 上传请求已经结束 |
| -50302 | TICLOUDSTORAGE_E_UPLOAD_RANGE_INVALID | 上传时间范围无效 |
| -50303 | TICLOUDSTORAGE_E_TOO_MANY_UPLOADS | 同一 Service 的活动上传请求达到上限 |
| -50304 | TICLOUDSTORAGE_E_UPLOAD_START_TIMEOUT | 等待视频关键帧超时 |
| -50400 | TICLOUDSTORAGE_E_AUTH_FAILED | 鉴权失败或 Token 无效 |
| -50401 | TICLOUDSTORAGE_E_NETWORK_UNAVAILABLE | 网络不可用 |
| -50402 | TICLOUDSTORAGE_E_NETWORK_TIMEOUT | 请求超时 |
| -50403 | TICLOUDSTORAGE_E_RATE_LIMITED | 被限流 |
| -50404 | TICLOUDSTORAGE_E_SERVER_UNAVAILABLE | 服务暂不可用 |
| -50405 | TICLOUDSTORAGE_E_PROTOCOL_ERROR | 与云端的协议交互失败 |
| -50500 | TICLOUDSTORAGE_E_CACHE_FULL | 持久化缓存空间不足 |
| -50501 | TICLOUDSTORAGE_E_CACHE_CORRUPTED | 持久化缓存损坏 |
| -50502 | TICLOUDSTORAGE_E_CACHE_IN_USE | 持久化缓存正被占用 |
TiCloudStorageGetErrorString
const char *TiCloudStorageGetErrorString(int error);返回只读诊断文本。业务分支应比较错误码，不要解析字符串。
版本与构建信息
TiCloudStorageGetVersion
const char *TiCloudStorageGetVersion(void);返回 SDK 版本字符串。
TiCloudStorageGetBuildInfo
const char *TiCloudStorageGetBuildInfo(void);返回版本、Git 提交、构建时间、目标平台、构建类型和编译器等诊断信息。展示格式可能扩展，不要作为稳定协议解析。
基础类型与配置
TiCloudStorageOptions
| 字段 | 说明 |
|---|---|
struct_size | 必须设置为结构体大小，推荐使用 TICLOUDSTORAGE_OPTIONS_INITIALIZER |
endpoint | 服务地址；NULL 使用内置公有云地址 |
log_level | 最低日志级别 |
on_log | 日志回调；消息只在回调期间有效，回调不能阻塞 |
TiCloudStorageLogLevel
| 常量 | 值 | 说明 |
|---|---|---|
TICLOUDSTORAGE_LOG_DEFAULT | 0 | 使用 SDK 默认级别，当前为 TICLOUDSTORAGE_LOG_INFO |
TICLOUDSTORAGE_LOG_TRACE | 1 | 输出 Trace 及以上级别日志 |
TICLOUDSTORAGE_LOG_DEBUG | 2 | 输出 Debug 及以上级别日志 |
TICLOUDSTORAGE_LOG_INFO | 3 | 输出 Info 及以上级别日志 |
TICLOUDSTORAGE_LOG_WARN | 4 | 输出 Warn 及以上级别日志 |
TICLOUDSTORAGE_LOG_ERROR | 5 | 只输出 Error 级别日志 |
TICLOUDSTORAGE_LOG_NONE | 6 | 关闭 SDK 日志输出 |
TiCloudStorageMedia
音频编号包括 PCM、A-law、AAC、Opus、μ-law 和 G.726；视频编号包括 JPEG、H.264 和 H.265。
| 常量 | 值 | 媒体格式 |
|---|---|---|
TICLOUDSTORAGE_AUDIO_PCM | 1 | PCM 音频 |
TICLOUDSTORAGE_AUDIO_ALAW | 2 | G.711 A-law 音频 |
TICLOUDSTORAGE_AUDIO_AAC | 3 | AAC 音频 |
TICLOUDSTORAGE_AUDIO_OPUS | 4 | Opus 音频 |
TICLOUDSTORAGE_AUDIO_ULAW | 5 | G.711 μ-law 音频 |
TICLOUDSTORAGE_AUDIO_G726 | 6 | G.726 音频 |
TICLOUDSTORAGE_VIDEO_JPEG | 65 | JPEG 视频帧 |
TICLOUDSTORAGE_VIDEO_H264 | 66 | H.264 视频 |
TICLOUDSTORAGE_VIDEO_H265 | 67 | H.265 视频 |
媒体编号范围由下列常量界定：
| 常量 | 值 | 说明 |
|---|---|---|
TICLOUDSTORAGE_AUDIO_MIN | 1 | 音频编号下界，与 TICLOUDSTORAGE_AUDIO_PCM 相同 |
TICLOUDSTORAGE_AUDIO_MAX | 64 | 音频编号上界 |
TICLOUDSTORAGE_VIDEO_MIN | 65 | 视频编号下界，与 TICLOUDSTORAGE_VIDEO_JPEG 相同 |
TICLOUDSTORAGE_VIDEO_MAX | 127 | 视频编号上界 |
TICLOUDSTORAGE_IS_AUDIO(media) 和 TICLOUDSTORAGE_IS_VIDEO(media) 只判断编号是否位于上述范围。音频编号 7～64 和视频编号 68～127 是预留值，被宏判为对应类别不表示 SDK 支持该格式。宏会多次求值参数，不要传入自增、函数调用等有副作用的表达式。
TiCloudStorageFrameInfo
| 字段 | 说明 |
|---|---|
channel_id | 0～255；同一采集通道的音视频使用相同 ID |
media | 一个 TICLOUDSTORAGE_AUDIO_* 或 TICLOUDSTORAGE_VIDEO_* 值 |
flags | 视频关键帧标志或音频采样类型 |
reserved | 必须为 0 |
timestamp_ms | 大于 0 的 UTC Unix 毫秒 |
length | 完整编码帧字节数 |
上传任务覆盖当前 Service 的全部媒体通道，不通过 channel_id 选择部分通道。
视频帧的 flags 取值如下：
| 常量 | 值 | 说明 |
|---|---|---|
0 | 0 | 非关键帧 |
TICLOUDSTORAGE_FRAME_FLAG_KEY_FRAME | 0x01 | 关键帧；JPEG 在上传队列中始终按关键帧处理，供客户端播放时仍应设置该标志 |
H.264 和 H.265 关键帧必须携带完整参数集，并设置 TICLOUDSTORAGE_FRAME_FLAG_KEY_FRAME。C SDK 从关键帧开始上传并自动完成后续分片，应用不需要管理分片边界。完整要求见上传录像。
音频帧的 flags 必须使用下列采样格式之一：
| 常量 | 值 | 采样格式 |
|---|---|---|
TICLOUDSTORAGE_AUDIO_SAMPLE_8K16B1C | 0 | 8 kHz、16 位、单声道 |
TICLOUDSTORAGE_AUDIO_SAMPLE_16K16B1C | 1 | 16 kHz、16 位、单声道 |
TICLOUDSTORAGE_AUDIO_SAMPLE_8K16B2C | 2 | 8 kHz、16 位、双声道 |
TICLOUDSTORAGE_AUDIO_SAMPLE_16K16B2C | 3 | 16 kHz、16 位、双声道 |
生命周期
TiCloudStorageInit
int TiCloudStorageInit(const struct TiCloudStorageOptions *options);初始化进程级资源。同一时刻只能成功初始化一次；options 可以为 NULL。
TiCloudStorageUninit
int TiCloudStorageUninit(void);调用前必须销毁全部 Service。成功返回后不再触发任何回调。
Service
TiCloudStorageServiceOptions
| 字段 | 说明 |
|---|---|
struct_size | 必须设置，推荐使用 TICLOUDSTORAGE_SERVICE_OPTIONS_INITIALIZER |
on_token_will_expire / on_token_expired | Token 到期通知 |
user_data | Service 级业务上下文，销毁返回前保持有效 |
device_secret_key | 必填，SDK 会复制且不得写入日志 |
buffer_size_bytes | 最近帧环形队列容量，0 使用默认值 |
cache_dir / cache_size_bytes | 可选持久化缓存目录和容量 |
token_expire_warning_sec | 到期前预警秒数，0 关闭预警 |
max_key_frame_interval_ms | 最大关键帧间隔，用于计算起始关键帧等待超时 |
所有 Service 回调由回调分发线程执行，不能阻塞，也不能在回调内调用 Stop、Destroy 或 Uninit。Token 回调可以调用 TiCloudStorageServiceUpdateToken()。
TiCloudStorageServiceCreate
int TiCloudStorageServiceCreate(
const char *device_id,
const struct TiCloudStorageServiceOptions *options);一个 Service 是一条独立媒体时间线，也是队列和上传任务的资源隔离边界。成功返回进程内唯一的正数 service_id。
TiCloudStorageServiceUpdateToken
int TiCloudStorageServiceUpdateToken(int service_id, const char *access_token);可以在启动前或运行期间设置 device_access_token。Token 过期会暂停云端传输，但不停止写队列或清空任务；更新有效 Token 后自动继续。
TiCloudStorageServiceStart
int TiCloudStorageServiceStart(int service_id);启动后才接受写帧和上传请求。没有有效 Token 不影响本地启动，但云端传输会等待 Token。
TiCloudStorageServiceStop
int TiCloudStorageServiceStop(int service_id);调用前先停止送帧线程。本接口立即中止上传和网络传输，不排空队列或缓存；被中止请求不触发 on_result，尚未分发的回调会被丢弃。
TiCloudStorageServiceDestroy
int TiCloudStorageServiceDestroy(int service_id);只能销毁尚未启动或已经停止的 Service。成功后 service_id 失效。
上传任务
TiCloudStorageUploadRequestOptions
| 字段 | 说明 |
|---|---|
struct_size | 必须设置，推荐使用 TICLOUDSTORAGE_UPLOAD_REQUEST_OPTIONS_INITIALIZER |
start_time_ms | 搜索起始视频关键帧的时间下界；可用 TICLOUDSTORAGE_TIME_EARLIEST |
duration_ms | 0 表示持续到显式 SetEnd；正数从实际起始关键帧计算结束边界 |
on_progress | 一段媒体上传成功或确认失败时返回该段结果；一个请求可以触发多次 |
on_result | 请求关闭后触发一次；正常完成时返回唯一的最终结果 |
user_data | 请求级业务上下文，按回调生命周期保持有效 |
回调中的结构体和字符串只在回调期间有效，需要异步处理时先复制。on_progress 的范围属于融合录像文件，不区分 channel_id。
TiCloudStorageUploadRequest
int TiCloudStorageUploadRequest(
int service_id,
const struct TiCloudStorageUploadRequestOptions *options);成功返回正数 upload_id，只表示请求已受理。任意视频通道的第一个合法关键帧都可以启动请求；音频不能单独启动请求。等待关键帧超时后，通过 on_result 返回 TICLOUDSTORAGE_E_UPLOAD_START_TIMEOUT。
start_time_ms 最多晚于当前 UTC 时间 TICLOUDSTORAGE_MAX_FUTURE_START_MS（10 秒）。更早的时间能否命中，取决于环形队列是否仍保留对应关键帧。
TiCloudStorageUploadSetEnd
int TiCloudStorageUploadSetEnd(
int service_id,
int upload_id,
uint64_t end_time_ms);end_time_ms 是右开边界。重复设置相同值幂等成功，可以向前收缩但不能向后扩大。返回成功只表示新边界已接受，最终结果以 on_result 为准。
TiCloudStorageUploadResult
| 常量 | 值 | 说明 |
|---|---|---|
TICLOUDSTORAGE_UPLOAD_COMPLETE | 0 | 所选媒体范围连续、完整地上传到云端 |
TICLOUDSTORAGE_UPLOAD_PARTIAL | 1 | 至少形成一段可播放录像，但成功范围存在缺口 |
TICLOUDSTORAGE_UPLOAD_FAILED | 2 | 没有形成任何可播放的录像区间 |
收到 TICLOUDSTORAGE_UPLOAD_PARTIAL 时，net_duration_ms < end_time_ms - start_time_ms。判断最终结果时，同时检查 error、请求与成功范围、累计时长和 size_bytes。
TiCloudStorageUploadRange
| 字段 | 说明 |
|---|---|
start_time_ms | 这段连续媒体的开始时间，包含该时间点 |
end_time_ms | 这段连续媒体的结束时间，不包含该时间点 |
size_bytes | 云端确认成功的实际上传字节数；失败回调中为 0，不包含重试产生的重复流量 |
on_progress 使用这个结构返回一段融合录像的处理结果。范围不对应单独的 channel_id，回调返回后结构体失效。
扩展上传配置
以下接口声明在 ticloudstorage_ext.h。
TiCloudStorageSetUploadQueueSize
int TiCloudStorageSetUploadQueueSize(int service_id, int max_slices);把上传队列长度设置为 1～6 个切片，默认值为 2。只能在创建 Service 后、启动前调用；队列已满时丢弃最旧的待传切片，并把缺口计入对应请求的最终结果。
TiCloudStorageSetUploadForceHttp
int TiCloudStorageSetUploadForceHttp(int force);传入非 0 值后，上传请求强制使用不带 TLS 的 HTTP；传入 0 恢复当前构建的默认行为。这个配置全局生效，仅用于明确需要明文 HTTP 的受控测试环境，不要在生产环境中启用。
媒体帧队列
TiCloudStorageQueueGetInfo
int TiCloudStorageQueueGetInfo(
int service_id,
struct TiCloudStorageQueueInfo *info);返回容量、已用空间、已进入上传处理但尚未释放的数据量、帧数、最早/最新帧和最早/最新关键帧时间。inflight_bytes 包含等待上传、正在传输和等待重试的数据；持续升高表示上传处理落后于写入速度。
TiCloudStorageQueueWriteFrame
int TiCloudStorageQueueWriteFrame(
int service_id,
const struct TiCloudStorageFrameInfo *frame_info,
const void *frame);SDK 在函数返回前复制结构体和完整帧。本接口线程安全，但应用必须保证同一 channel_id、同一媒体类型的时间戳单调不减；不同通道之间不要求全局重排。
返回成功只表示环形队列已接收当前帧，不表示已经上传，也不表示编码数据能够被客户端播放。编码格式、关键帧和音频数据的要求见上传录像。