基于IOTCAPIs的局域网设备搜索_影像传输

一、功能概述

TUTK SDK 的 IOTCAPIs 提供一套局域网设备搜索接口，支持在同一路由器下发现在线设备。核心用于 APP 端快速获取局域网内的设备列表，为后续连接、控制等操作提供基础。

当前推荐使用「IOTC_Search_Device_Start + IOTC_Search_Device_Stop + IOTC_Search_Device_Result」组合接口，另外两个旧接口已废弃，不建议新开发使用。

二、API列表说明

局域网搜索相关API共3组，其中2组已废弃，1组为当前推荐使用接口：

API名称	状态	功能描述	备注
`IOTC_Lan_Search2`	已废弃	局域网设备搜索（旧版接口）	无替代场景，不建议使用
`IOTC_Lan_Search2_Ex`	已废弃	增强版局域网设备搜索（旧版接口）	无替代场景，不建议使用
`IOTC_Search_Device_Start` `IOTC_Search_Device_Stop` `IOTC_Search_Device_Result`	推荐使用	启动搜索 + 停止搜索 + 获取结果组合接口	支持自定义超时时间、搜索间隔，非阻塞获取结果

三、使用示例（推荐方案）

以下示例以 C 语言为例，展示完整的局域网设备搜索流程：启动搜索 → 循环获取结果 → 停止搜索。支持最多发现20台设备，非阻塞模式避免UI卡顿。

#include 
#include 
#include "IOTCAPIs.h"

// 中断请求标志（用于控制搜索循环退出，可根据实际业务调整）
static volatile int isInterruptionRequested = 0;

// 模拟中断请求（如用户点击取消按钮时调用）
void requestInterruption() {
    isInterruptionRequested = 1;
}

int main() {
    // 设备搜索结果结构体数组（最多存储20台设备，SDK推荐上限）
    struct st_SearchDeviceInfo devices[20];
    int deviceCount = 0;

    // 1. 启动设备搜索
    // 参数1：搜索超时时间（ms），3000ms=3秒
    // 参数2：搜索间隔（ms），100ms=0.1秒
    int startRet = IOTC_Search_Device_Start(3000, 100);
    if (startRet != 0) {
        printf("启动设备搜索失败，错误码：%d\n", startRet);
        return -1;
    }
    printf("设备搜索已启动，超时时间3秒...\n");

    // 2. 循环获取搜索结果（直到收到中断请求或超时）
    while (!isInterruptionRequested) {
        // 获取搜索结果
        // 参数1：设备信息存储数组指针
        // 参数2：数组长度（最多20）
        // 参数3：获取模式（0=仅返回新发现设备，1=返回所有已发现设备）
        int ret = IOTC_Search_Device_Result(devices, 20, 0);
        
        if (ret < 0) {
            // 搜索出错，退出循环
            printf("获取设备搜索结果失败，错误码：%d\n", ret);
            break;
        } else if (ret > 0) {
            // 发现新设备，更新设备计数并打印设备信息
            deviceCount = ret;
            printf("\n本次发现%d台新设备：\n", deviceCount);
            for (int i = 0; i < deviceCount; i++) {
                printf("  设备%d：\n", i + 1);
                printf("    UID：%s\n", devices[i].UID);          // 设备唯一标识
                printf("    设备名称：%s\n", devices[i].DeviceName); // 自定义设备名称（需设备端配置）
                printf("    IP地址：%s\n", devices[i].IP);        // 设备局域网IP
            }
        }
        // ret=0 时无新设备，不处理

        // 每隔1秒查询一次结果（避免频繁调用占用资源）
        usleep(1000 * 1000); // 单位：微秒，1000*1000=1秒
    }

    // 3. 停止设备搜索，释放SDK内部资源
    IOTC_Search_Device_Stop();
    printf("\n设备搜索已停止，累计发现%d台设备\n", deviceCount);

    return 0;
}

示例说明

• 搜索启动：IOTC_Search_Device_Start 传入超时时间和搜索间隔，SDK 内部自动发送广播包搜索设备；

• 结果获取：IOTC_Search_Device_Result 采用非阻塞模式（参数3=0），避免阻塞主线程，ret 为本次新发现的设备数量；

• 搜索停止：无论正常结束还是异常退出，都需调用 IOTC_Search_Device_Stop 释放资源，避免内存泄漏。

四、核心API参数详解

重点讲解推荐方案中3个接口的参数、返回值及结构体定义：

（一）IOTC_Search_Device_Start

函数原型：int32_t IOTC_Search_Device_Start(int32_t nTimeoutMs, int32_t nIntervalMs)

功能：启动局域网设备搜索，SDK 内部开始发送广播包探测设备。

参数	类型	说明	取值范围
nTimeoutMs	int32_t（输入）	搜索超时时间（毫秒）	≥1000ms（推荐3000~5000ms）
nIntervalMs	int32_t（输入）	广播包发送间隔（毫秒）	50~500ms（推荐100ms）

返回值：0 表示启动成功，负数表示启动失败（错误码参考SDK错误码文档）。

（二）IOTC_Search_Device_Stop

函数原型：void IOTC_Search_Device_Stop(void)

功能：停止局域网设备搜索，释放 SDK 内部的搜索资源（如广播线程、缓存等）。

参数：无输入参数。

返回值：无返回值。

（三）IOTC_Search_Device_Result

函数原型：int32_t IOTC_Search_Device_Result(struct st_SearchDeviceInfo* psSearchDeviceInfo, int32_t nArrayLen, int32_t nGetAll)

功能：获取当前搜索到的设备列表，支持按需返回新设备或所有设备。

参数	类型	说明	取值/约束
psSearchDeviceInfo	struct st_SearchDeviceInfo*（输出）	设备信息数组指针，用于存储搜索结果	需提前分配内存，数组长度≥1
nArrayLen	int32_t（输入）	设备信息数组的最大长度	最大支持20（SDK 内部限制）
nGetAll	int32_t（输入）	结果返回模式	0=仅返回新发现设备；1=返回所有已发现设备

返回值：

• 正数：本次返回的设备数量（≤nArrayLen）；

• 0：无新设备（nGetAll=0时）或已返回所有设备（nGetAll=1时）；

• 负数：获取结果失败（错误码参考SDK错误码文档）。

（四）设备信息结构体 st_SearchDeviceInfo

存储单台设备的核心信息，结构体定义如下（具体字段以SDK头文件为准）：

struct st_SearchDeviceInfo {
    char UID[64];          // 设备唯一标识（核心字段）
    char IP[16];           // 设备局域网IP地址（如"192.168.1.100"）
    char DeviceName[128];  // 自定义设备名称（需设备端调用IOTC_Set_Device_Name配置）
    uint16_t Port;         // 设备监听端口
    uint8_t Mac[6];        // 设备MAC地址
    // 其他扩展字段（根据SDK版本可能新增）
};

五、开发Tips

1. 隐藏设备UID，使用自定义标识

若不想在搜索过程中暴露设备 UID（唯一标识），可通过以下方式配置自定义标识：

• 设备端：调用 IOTC_Set_Device_Name(const char* user_define_string) 设置自定义字符串（如设备型号、昵称等）；

• APP端：通过 st_SearchDeviceInfo.DeviceName 获取该自定义标识，替代 UID 用于设备展示或识别。

2. 自定义局域网搜索端口

SDK 默认使用 32761 端口发送广播包进行设备搜索，若需修改端口（如避免端口冲突），可调用：

int32_t IOTC_Set_LanSearchPort(uint16_t nPort)

注意：设备端需同步适配该端口，否则会导致搜索失败。建议仅在必要时修改，优先使用默认端口。

六、注意事项

以下注意事项直接影响搜索功能的稳定性和准确性，请严格遵循：

1. 数组长度限制

IOTC_Search_Device_Result 的 nArrayLen 最大支持20，即单次搜索最多返回20台设备。若局域网内设备超过20台，需分批获取或扩大搜索范围。

2. 调用时机顺序

必须先调用 IOTC_Search_Device_Start 启动搜索，再调用 IOTC_Search_Device_Result 获取结果，最后调用 IOTC_Search_Device_Stop 停止搜索，不可颠倒顺序。

3. 非阻塞模式使用

建议将 nGetAll 设置为 0（仅返回新设备），并在循环中调用 IOTC_Search_Device_Result，避免阻塞主线程（尤其是 UI 线程）导致界面卡顿。

4. 超时时间设置

nTimeoutMs 建议设置为 3000~5000ms：时间过短可能导致设备未响应就停止搜索，时间过长会影响用户体验。

5. 资源释放

无论搜索是否成功（正常结束、超时、异常出错），都必须调用 IOTC_Search_Device_Stop 释放资源，否则会导致 SDK 内部线程泄漏或内存占用过高。

6. 跨网段限制

该套接口仅支持同一路由器下的局域网搜索，不支持跨网段、跨路由设备发现。若需外网搜索，需使用 TUTK 云搜索相关接口。