C SDK 接入

在设备端工程中接入 TiRTC C SDK，完成运行时初始化，并根据设备环境选择 SDK 日志输出方式。

完成本页后，继续连接设备。连接成功后，再实现音视频、语音对讲、命令消息或流消息。

获取二进制库

先从下载 C SDK获取匹配的 C SDK。

拿到压缩包后，不要只拷贝 include/ 和 lib/。请先完整查看包内 README.md、manifest/ 以及包内声明的构建契约文件，再开始接入。对 MCU / RTOS / mini 预编译包，这些文件和头文件一起构成运行合同；如果只按本文的通用初始化步骤接入，可能出现“编译通过，但运行时因 RTOS、PSRAM、线程栈、socket 或板级网络前置条件不匹配而崩溃”的情况。

不同平台的库文件名会有差异，但对外 C API 入口一致。以 Linux x86_64 标准包为例，解压后目录结构如下：

text

tirtc-c-sdk/
|-- include/
|   `-- tirtc/
|       |-- basedef.h
|       `-- tiRTC.h
`-- lib/
    |-- libTiRTC.a
    `-- libTiRTC.so

业务代码只需要包含 include/tirtc/tiRTC.h。basedef.h 是 tiRTC.h 依赖的公开头文件，需要和 tiRTC.h 一起保留在 include/tirtc/ 目录下。

在工程中引用

把 SDK 的 include/ 目录加入头文件搜索路径，然后链接包内提供的 TiRTC 入口库。

业务代码推荐这样包含头文件：

#include <tirtc/tiRTC.h>

Linux 标准包提供两种接入方式：

静态接入：编译期链接 lib/libTiRTC.a。
动态接入：编译期链接 lib/libTiRTC.so，运行时确保程序能找到这个 .so 文件，例如放在系统库目录、程序约定的库目录，或配置 LD_LIBRARY_PATH / rpath。

其他设备平台包通常提供静态库，按静态链接接入即可。

初始化 SDK

TiRtcInit() 用来初始化 SDK 运行时，函数内部无网络交互，可以在设备连通互联网之前调用。

#include <signal.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>

#include <tirtc/tiRTC.h>

static volatile sig_atomic_t g_should_exit = 0;

static void on_signal(int signo)
{
    (void)signo;
    g_should_exit = 1;
}

int main(int argc, char **argv)
{
    signal(SIGINT, on_signal);
    signal(SIGTERM, on_signal);

    if (TiRtcInit() != 0) {
        return 1;
    }

    while (!g_should_exit) {
        sleep(1);
    }

    TiRtcUninit();
    return 0;
}

配置 SDK 日志输出

是否保存 SDK 日志由应用决定，不影响 SDK 启动。但应在接入阶段决定怎样取得日志。开发和联调时可以直接观察控制台输出；设备投入现场后通常不便随时连接调试接口，建议保留容量受控、可以从设备取回的日志。这样问题发生后可以还原现场，不必接入调试接口后重新复现。

在 TiRtcInit() 之后、TiRtcStart() 之前，根据设备平台和日志用途选择输出方式：

需要	适用平台	配置方式
实时查看日志	Linux	通过 `TiRtcLogConfig()` 输出到控制台
由 SDK 保存日志文件	Linux	通过 `TiRtcLogConfig()` 设置文件路径和文件大小上限
交给应用保存或转发	所有设备平台	通过 `TiRtcLogSetCallback()` 额外取得一份 SDK 日志

在 Linux 上输出和保存日志

下面的示例同时把日志输出到控制台，并保存到已挂载的 SD 卡：

TiRtcInit();

TiRtcLogConfig(
    1,
    "/mnt/sdcard/tirtc/device.log",
    4U * 1024U * 1024U
);
TiRtcLogSetLevel(4);

TiRtcLogConfig() 仅在 Linux 平台有效。第一个参数为非 0 时，SDK 同时把错误日志输出到 stderr，把其他日志输出到 stdout；传 0 时不输出到控制台。第二个参数是文件路径，建议使用绝对路径，避免工作目录变化后写入其他位置；传 NULL 表示不写文件。第三个参数限制日志文件的最大字节数，超出后滚动覆盖。

SD 卡只是文件路径所在的存储介质，不是 SDK 的专用日志能力。调用前需要完成挂载、创建父目录，并确认进程具有写权限。也可以把路径设置到其他可写文件系统。如果只需要在开发阶段实时查看日志，可以传入 TiRtcLogConfig(1, NULL, 0)。

通过回调自定义日志去向

需要接入已有日志系统，或者设备不是 Linux 平台时，使用 TiRtcLogSetCallback() 额外取得 SDK 日志：

static void on_tirtc_log(const char *log, uint32_t length)
{
    app_log_enqueue_copy(log, length); // 由应用实现，并在返回前复制日志内容
}

TiRtcInit();
TiRtcLogSetCallback(on_tirtc_log);
TiRtcLogSetLevel(4);

示例中的 app_log_enqueue_copy() 不是 TiRTC API。log 指向的内容只在本次回调期间有效，也不保证以 NUL 结尾；需要保留时，应在回调返回前按 length 复制到应用自己的缓冲区。回调在产生日志的线程中同步执行，并可能来自不同线程，因此处理函数需要保证线程安全并尽快返回。写入 SD 卡、Flash 或上传等可能阻塞的操作，应交给应用任务异步处理。

应用可以把队列中的日志输出到平台日志系统，也可以写入 SD 卡、Flash、环形缓冲区或上传通道。自行保存日志时，还需要为队列和日志文件设置容量上限、滚动或丢弃策略，并处理存储不可用或写入失败的情况，避免日志无限增长。

设置回调不会关闭 SDK 原有的控制台或文件输出；SDK 会同时把日志内容传给应用。传入 TiRtcLogSetCallback(NULL) 可以停止回调。

非 Linux 平台的 TiRtcLogConfig() 不生效。在使用 printf、stdout 或 stderr 作为默认控制台的设备上，日志最终是否通过 UART 输出取决于芯片 SDK 和固件配置；其他设备由各自的平台控制台适配决定。需要明确控制日志去向时，应通过回调接入应用自己的日志链路。

完成配置后，在首次启动 SDK 时确认控制台、日志文件或回调中能够看到日志。Linux 文件没有产生内容时，先检查挂载状态、父目录和写入权限；回调没有收到内容时，确认应用已经注册回调，且后续代码没有将它清除。问题发生后怎样定位和提交日志，参考排查接入问题。

为 4G 设备补充网络初始化配置

SDK 无法感知设备当前网络的访问限制，因此需要你在 TiRtcStart() 前主动提供相关网络信息。SDK 会根据这些信息适配对应网络。

部分 4G 定向卡会通过域名或 IP 地址白名单限制设备可以访问的地址。这类网络也常被称为 4G 白名单网络，本文统一称为受限网络。

通过 TiRtcSetOption 设置 TIRTC_OPT_RESTRICTED_NETWORK，可以把这类访问限制告诉 SDK。设备直接使用受限的物联网卡，或者通过 Wi-Fi 接入使用此类物联网卡的路由器，都应设置为 1；普通 4G 网络设置为 0。如果你不清楚当前网络的访问限制，可以向 SIM 卡运营商或方案商确认。

设备直接使用 4G 网络时，还需要设置 TIRTC_OPT_NETWORK_TYPE 和 TIRTC_OPT_ICCID。TIRTC_OPT_NETWORK_TYPE 只描述设备自身直接使用的联网方式。设备连接 Wi-Fi 时应设置为 TIRTC_NETCONN_WIFI，即使上游路由器通过 4G 联网，也不要设置为 TIRTC_NETCONN_4G。

TIRTC_OPT_ICCID 只填写设备直接使用的 4G SIM 卡 ICCID。设备通过 Wi-Fi 联网时，不填写上游路由器内 SIM 卡的 ICCID。

设备联网场景	`TIRTC_OPT_NETWORK_TYPE`	`TIRTC_OPT_ICCID`	`TIRTC_OPT_RESTRICTED_NETWORK`
普通 4G 网络	`TIRTC_NETCONN_4G`	当前 SIM 卡 ICCID，必填	显式设置为 `0`
受限网络，设备直接通过 4G 联网	`TIRTC_NETCONN_4G`	当前 SIM 卡 ICCID，必填	显式设置为 `1`
受限网络，设备通过 Wi-Fi 接入	`TIRTC_NETCONN_WIFI`	不需要提供路由器内 SIM 卡的 ICCID	设置为 `1`

下面的示例适用于设备直接使用 4G SIM 卡联网：

static int set_4g_network_options(const char *iccid, int restricted_network)
{
    int network_type = TIRTC_NETCONN_4G;
    int code;

    if (iccid == NULL || iccid[0] == '\0') {
        return TIRTC_E_INVALID_PARAMETER;
    }
    if (restricted_network != 0 && restricted_network != 1) {
        return TIRTC_E_INVALID_PARAMETER;
    }

    code = TiRtcSetOption(TIRTC_OPT_NETWORK_TYPE, &network_type,
                          (uint32_t)sizeof(network_type));
    if (code != 0) {
        return code;
    }

    code = TiRtcSetOption(TIRTC_OPT_ICCID, iccid,
                          (uint32_t)strlen(iccid));
    if (code != 0) {
        return code;
    }

    return TiRtcSetOption(TIRTC_OPT_RESTRICTED_NETWORK,
                          &restricted_network,
                          (uint32_t)sizeof(restricted_network));
}

调用顺序为：TiRtcInit() → 设置上述三个网络选项 → TiRtcStart()。

下一步

完成 C SDK 引用和初始化，并确定日志输出方式后，继续参考连接设备，设置设备密钥 device_secret_key 和启动时上报的标识 client_id，再完成 TiRtcStart() 启动和客户端建连处理。

C SDK 接入 ​

获取二进制库 ​

在工程中引用 ​

初始化 SDK ​

配置 SDK 日志输出 ​

在 Linux 上输出和保存日志 ​

通过回调自定义日志去向 ​

为 4G 设备补充网络初始化配置 ​

下一步 ​