C SDK 接入
下载并选择二进制库
从下载 C SDK页面选择与目标操作系统、CPU 架构和工具链匹配的下载包。下载后，使用同一包中的头文件和二进制库完成接入，不要混用不同下载包中的文件。
引入头文件和二进制库
将下载包的 include 目录加入编译器的头文件搜索路径，然后引用公共头文件：
#include <tirtc/ticloudstorage.h>静态接入链接 lib/libTiRTC.a。下载包同时提供动态库时，也可以按目标平台链接 libTiRTC.so 或 libTiRTC.dylib，并在部署时将动态库及包内声明的运行时依赖放在系统能够加载的位置。具体方式以目标平台的动态库加载规则和包内说明为准。
排查运行问题时，在日志中记录 TiCloudStorageGetVersion() 和 TiCloudStorageGetBuildInfo() 的返回值，并附上所用 SDK 包名。
加载设备凭证并获取 Token
创建上传 Service 前，设备应用需要取得 device_id、device_secret_key 和 device_access_token。前两项是设备的长期凭证，Token 则由设备在运行时向业务服务端获取。
从设备中读取长期凭证
采购设备凭证后，探鸽平台会为每台设备提供一组相互匹配的 device_id 和 device_secret_key。量产时，由你的生产或灌装系统把这组凭证与具体设备绑定，并写入设备的持久化存储：
device_id是设备的稳定标识，可以保存在设备信息区、配置分区或其他可持久读取的位置。device_secret_key是设备密钥，应保存在设备提供的安全存储中，例如安全芯片、TEE、密钥存储区或受保护的持久化分区。
设备启动后，设备应用通过已有的设备信息或配置接口读取这两个值。把 device_id 传给 TiCloudStorageServiceCreate()，并把 device_secret_key 写入 TiCloudStorageServiceOptions。
具体存储位置和读取接口由设备平台决定。Ti 云存 SDK 接收设备应用读出的凭证，不直接读写设备的 Flash、配置分区或安全芯片。
开发和联调阶段尚未接入生产灌装流程时，可以从受控的本地配置中加载测试设备凭证。该配置应与源码和公共固件包分开保存。
向业务服务端获取 Token
设备应用使用产品已有的设备鉴权方式请求自己的业务服务端。业务服务端确认设备身份后，使用对应的 device_id 调用 /issue-device-access-token。业务服务端再把返回的 access_token 和 expires_at_ms 下发给设备。设备取得 Token 后，调用 TiCloudStorageServiceUpdateToken() 交给 SDK。
设备怎样访问业务服务端，以及使用什么协议和鉴权方式，由你的业务系统定义。需要 AccessKeySecret 签名的 Ti 云存 HTTP API 由业务服务端调用，AccessKeySecret 保存在可信业务服务端。
复用和续签 Token
device_access_token 有明确的过期时间。Token 是否有效取决于 expires_at_ms 和当前授权状态，不按上传请求或 API 调用次数消耗。同一设备休眠唤醒或重新创建 Service 后，只要 Token 仍然有效，就可以继续使用。
设备接收 Token 时，应同时保存业务服务端返回的 expires_at_ms。如果需要跨休眠保存 Token，应把二者作为一组敏感数据保护。设备恢复后，根据 Token 状态决定是否续签：
| Token 状态 | 设备应用的处理方式 |
|---|---|
尚未接近 expires_at_ms | 继续使用当前 Token；如果重新创建了 Service，调用 TiCloudStorageServiceUpdateToken() 再次设置 |
已接近过期时间，或收到 on_token_will_expire | 向业务服务端获取新 Token，再调用 TiCloudStorageServiceUpdateToken() 更新 |
已经过期，或收到 on_token_expired | 获取并更新 Token；SDK 随后恢复该 Service 的云端传输 |
| 无法可靠判断当前 UTC 时间 | 获取新 Token，并以服务端返回的新过期时间为准 |
Token 尚未到期也可能因鉴权失败而无法继续使用。如果 SDK 报告 TICLOUDSTORAGE_E_AUTH_FAILED 或触发 on_token_expired，先检查 device_id、device_secret_key、Token 和当前授权是否匹配。修正问题后，重新获取 Token 并调用 TiCloudStorageServiceUpdateToken()。
如需接收 Token 临期通知，在 TiCloudStorageServiceOptions 中设置 token_expire_warning_sec 并注册 on_token_will_expire。同时注册 on_token_expired，用于接收过期通知。Token 过期时，SDK 暂停当前 Service 的云端传输，但继续接收媒体帧并保留上传任务。更新为有效 Token 后，云端传输自动继续。
Token 回调由 SDK 的回调线程执行。设备应用应把续签任务交给业务线程，避免在回调中执行网络请求。
Token 的签发方式见云端签发 Token。
初始化 SDK 并启动上传服务
- 使用
TICLOUDSTORAGE_OPTIONS_INITIALIZER初始化进程配置，并调用TiCloudStorageInit()。 - 使用
TICLOUDSTORAGE_SERVICE_OPTIONS_INITIALIZER初始化 Service 配置。设置device_secret_key，并按需配置帧队列和 Token 回调，再调用TiCloudStorageServiceCreate(device_id, &options)。 - 调用
TiCloudStorageServiceUpdateToken()设置device_access_token。 - 调用
TiCloudStorageServiceStart()。启动后才可以写帧和提交上传请求。 - 退出前等待每个上传请求的
on_result，再停止和销毁 Service，最后调用TiCloudStorageUninit()。
TiCloudStorageServiceStop() 会中止活动任务，被中止的请求不会再触发 on_result。如需取得每个请求的最终结果，应先等待对应的 on_result，再停止 Service。
下面是单 Service 应用的最小启动代码：
#include <tirtc/ticloudstorage.h>
static int init_and_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;
}同一进程创建多个 Service 时，只调用一次 TiCloudStorageInit()，再分别创建和启动各个 Service。TiCloudStorageServiceStart() 返回 TICLOUDSTORAGE_OK 后才可以提交上传请求和写帧。完整上传、最终结果判断与释放顺序见上传录像。