C SDK 接入

下载并选择二进制库

从下载 C SDK选择与目标操作系统、CPU 架构和工具链匹配的下载包。Ti 云存与 TiRTC 位于同一个 SDK 包；同一工程必须使用同一份下载包中的头文件和二进制库。

引入头文件和二进制库

把交付包的 include 目录加入编译器头文件搜索路径，把目标架构的库加入链接参数。业务代码引用公共头文件：

#include "ticloudstorage.h"

运行前确认动态库搜索路径和目标环境一致，并记录 TiCloudStorageGetVersion() 与 TiCloudStorageGetBuildInfo() 的结果。

读取设备身份并请求 Token

设备需要三个值：

值	来源	设备怎样使用
`device_id`	设备注册或交付流程提供的既有设备标识	按项目已经确认的配置或灌装方式加载；不要在固件中自行生成一个新值
`device_secret_key`	设备注册或交付流程与 `device_id` 配套提供的既有密钥	从对应设备的受控存储加载；只进入确有需要的设备管理流程，不通过普通业务日志、客户端或前端页面传递
`device_access_token`	业务服务端调用 `/issue-device-access-token` 签发	设备先用产品已有的设备鉴权方式请求自己的业务服务端，再接收服务端返回的 Token 和过期时间

C SDK 不会替设备登录业务系统，也不会主动请求业务服务端。设备应用需要实现这段网络交互；请求路径、协议和设备鉴权方式由你的业务系统定义。业务服务端确认设备身份后，使用应用级凭证调用 HTTP API，并且只向设备返回 device_access_token、过期时间和业务需要的保存策略信息。

不要让设备直接调用需要 AccessKeySecret 签名的 HTTP API。AccessKeySecret 只能留在可信业务服务端，不能写进固件。

SDK 触发 on_token_will_expire 或 on_token_expired 时，把续签任务投递到设备业务线程。业务线程重新请求自己的业务服务端，取得新 Token 后调用 TiCloudStorageServiceUpdateToken()；不要在回调线程中执行阻塞网络请求。

管理 Token 有效期和休眠唤醒

连接次数本身不会使 device_access_token 失效；Token 仍然有效且未到业务服务端返回的 expires_at_ms 时，可以继续使用。它不是一次性建连凭证，也不是可以永久保存的设备密钥。

当前 Token 仍然有效且尚未过期时，可以继续用于同一设备。设备不需要因为每次休眠唤醒或重新创建 Service 就机械地重新签发 Token。
设备接收 Token 时，同时保留 expires_at_ms。唤醒后如果 Token 已经过期或即将过期，先向业务服务端申请新 Token，再调用 TiCloudStorageServiceUpdateToken()。
Service 运行期间收到 on_token_will_expire 时，在业务线程提前续签；收到 on_token_expired 时，立即续签并更新 Token。
on_token_will_expire 和 on_token_expired 只报告到期状态。如果尚未到 expires_at_ms，但 SDK 接口返回或回调中的 error 报告 TICLOUDSTORAGE_E_AUTH_FAILED，就不能再只依据过期时间判断。先按鉴权失败检查设备身份、当前授权和应用配置；确认这些状态正常后，可以重新申请 Token，并调用 TiCloudStorageServiceUpdateToken() 尝试恢复。
Token 过期只暂停当前 Service 的云端传输，不停止写队列或清空上传任务；更新有效 Token 后自动继续。主动调用 TiCloudStorageServiceStop() 会中止活动上传任务；Service 停止并销毁后，新建 Service 不会自动恢复原任务。不能把 Token 复用理解为任务可以跨 Service 自动恢复。

唤醒后的 Token 状态	处理方式
仍然有效、尚未过期且未接近到期	继续使用当前 Token；上传期间收到到期预警时再续签
即将过期	先向业务服务端续签，再继续上传
已经过期	获取新 Token，并调用 `TiCloudStorageServiceUpdateToken()`
尚未到期，但报告 `TICLOUDSTORAGE_E_AUTH_FAILED`	按鉴权失败检查设备身份、当前授权和应用配置；确认正常后可重新申请并更新 Token
无法可靠判断当前 UTC 时间	获取新 Token，避免继续使用可能失效的凭证

device_id 和 device_secret_key 是设备长期身份信息，应按设备交付流程安全持久化。device_access_token 只作为短期上传授权使用；如需在设备端缓存，必须和过期时间一起保护，不要写入普通配置、日志或工单。Token 的签发范围和有效期见云端签发 Token。

初始化 SDK 并启动上传服务

使用 TICLOUDSTORAGE_OPTIONS_INITIALIZER 初始化进程配置，并调用 TiCloudStorageInit()。
使用 TICLOUDSTORAGE_SERVICE_OPTIONS_INITIALIZER 初始化 Service 配置。设置 device_secret_key、队列、缓存与回调后，调用 TiCloudStorageServiceCreate(device_id, &options)。
调用 TiCloudStorageServiceUpdateToken() 设置 device_access_token。
调用 TiCloudStorageServiceStart()。启动后才可以写帧和提交上传请求。
退出前等待每个上传请求的 on_result，再停止和销毁 Service，最后调用 TiCloudStorageUninit()。

TiCloudStorageServiceStop() 会立即中止活动任务，不会替应用等待上传排空。

最小初始化代码：

#include "ticloudstorage.h"

static int start_ti_cloud_storage(
    const char *device_id,
    const char *device_secret_key,
    const char *device_access_token
) {
    struct TiCloudStorageOptions options = TICLOUDSTORAGE_OPTIONS_INITIALIZER;
    int rc = TiCloudStorageInit(&options);
    if (rc != TICLOUDSTORAGE_OK) {
        return rc;
    }

    struct TiCloudStorageServiceOptions service =
        TICLOUDSTORAGE_SERVICE_OPTIONS_INITIALIZER;
    service.device_secret_key = device_secret_key;
    int service_id = TiCloudStorageServiceCreate(device_id, &service);
    if (service_id < 0) {
        TiCloudStorageUninit();
        return service_id;
    }

    rc = TiCloudStorageServiceUpdateToken(service_id, device_access_token);
    if (rc == TICLOUDSTORAGE_OK) {
        rc = TiCloudStorageServiceStart(service_id);
    }
    if (rc != TICLOUDSTORAGE_OK) {
        TiCloudStorageServiceDestroy(service_id);
        TiCloudStorageUninit();
        return rc;
    }
    return service_id;
}

TiCloudStorageServiceStart() 返回 TICLOUDSTORAGE_OK 后才可以提交上传请求和写帧。完整上传、最终结果判断与释放顺序见上传录像。

C SDK 接入 ​

下载并选择二进制库 ​

引入头文件和二进制库 ​

读取设备身份并请求 Token ​