C/C++ 远端设备 SDK API

/*
* @name :  TRRO_initJsonPath
* @brief : SDK初始化，读取指定路径文件初始化， 接口为同步阻塞模式，等待信令连接成功后返回
* @input : jsonPath   JSON文件路径
* @return : 成功 1 失败 <= 0
*/
int TRRO_initJsonPath(const char* jsonPath); 

/*
* @name :  TRRO_initJson
* @brief : SDK初始化，读取输入JSON字符串初始化， 接口为同步阻塞模式，等待信令连接成功后返回
* @input : json   JSON 配置字符串
* @return : 成功 1 失败 <= 0
*/
int TRRO_initJson(const char* json); 

//销毁SDK
extern "C" TRRO_EXPORT void TRRO_destroy();

/*
* @name :  TRRO_getGwList
* @brief : 获取在线现场设备设备列表，接口为同步阻塞模式
* @input : void
* @return : JSON 字符串
*           {"ret":0,"msg":"suc","gateways":[{"deviceID":"xx","name":"xx","type":"gateway","status":"connected","streams":4,"timestamp":1682231838673,"version":"xx"}],"count":1}
*/
const char* TRRO_getGwList();



/*
* @name :  TRRO_getGwList
* @brief : 获取对应网关的版本，接口为同步阻塞模式.
* @input : gwid 设备id 公有云含projectID前缀，形式如ProjectId/FieldDeviceId
* @return : json字符串, 使用方不需要释放指针, 获取到值后立即拷贝。
*           {"ret":0, "msg": "suc", "deviceID":"xx","name":"xx","type":"gateway","status":"connected","streams":4,"timestamp":1682231838673,"version":"xx","sdk_mode":"server2","ability":0,"licenseExpire":1745666980}
*/
extern "C" TRRO_EXPORT const char* TRRO_getGwInfo(const char* gwid);


/*
* @name :  TRRO_connect
* @brief : 发起视频连接，可多次调用连接不同流，异步模式，根据 onState 状态回调确认视频连接成功
* @input : gwid         目标连接的现场设备 ID， 公有云传设备ID时需要带上projectid前缀，如projectid/fieldDeviceId
*          record_config:
*                       优先使用录制配置，当默认录制配置命名规则无法满足需求时使用，JSON 字符串，需要对每一路进行配置 eg:"{\\"file_names\\": [{\\"file\\":\\"test\\", \\"duration\\":15}, {\\"file\\":\\"test01\\", \\"duration\\":15}]}"  ps:file 文件名 duration 分片时长单位秒
*          streams_num 要拉取现场设备视频流的个数， 与conn_fds和streams_num数组长度匹配， 值的范围 1 到 现场设备支持的device_streams数量
*          streams_id  现场设备视频流的 ID 数组， 现场设备视频流 ID 从0开始， 最大值为现场设备支持的 device_streams数量 -1
*          conn_fds    conn_fd数组，conn_fd为接收视频流的句柄标识，自行编号，取值从0开始，最大值为 max_streams -1，max_streams在远端设备配置文件配置
* @return : 成功 1 失败 <= 0
*/
int TRRO_connect(const char* gwid, const char* record_config, int streams_num, int* streams_id, int* conn_fds);


/*
* @name :  TRRO_connectField
* @brief : 发起视频连接，可多次调用连接不同流，异步模式，根据onState状态回调确认视频连接成功
* @input : gwid           目标连接的现场设备ID，公有云传设备ID时需要带上projectid前缀，如projectid/fieldDeviceId
*          streams_num    要拉取现场设备视频流的个数， 与conn_fds和streams_num数组长度匹配， 值的范围 1 到 现场设备支持的device_streams数量
*          streams_id     现场设备视频流的ID数组， 现场设备视频流ID从0开始， 最大值为现场设备支持的device_streams数量 -1
*          conn_fds       conn_fd数组，conn_fd为接收视频流的句柄标识，自行编号，取值从0开始，最大值为max_streams -1，max_streams在远端设备配置文件配置
*          compatible     是否开启版本兼容: 设置0，根据配置文件的“sdk_mode“字段来决定连接模式；设置为1，该接口会获取网关版本信息从而根据网关模式自动适配模式连接（由于需要获取版本信息会影响秒开）。默认值为0
*          record_config: 优先使用录制配置，当默认录制配置命名规则无法满足需求时使用，
                            json字符串，需要对每一路进行配置 eg:"{\\"file_names\\": [{\\"file\\":\\"test\\", \\"duration\\":15}, {\\"file\\":\\"test01\\", \\"duration\\":15}]}"  
                            ps:file 文件名 duration 分片时长单位秒; 不使用时默认为NULL
* @return : 成功 1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_connectField(const char* gwid, int streams_num, int* streams_id, int* conn_fds, int compatible = 0, const char* record_config = NULL);


/*
* @name :  TRRO_setWindows
* @brief : 设置接收流句柄对应的显示窗口句柄
* @input : conn_fds 接收视频流句柄数组
*          windows  显示窗口句柄数组， 显示窗口句柄为显示窗体的句柄/指针，如 Windows 平台的 HWND；
*                   外部渲染时，数组中的显示窗口句柄配置为 nullptr
*          num      设置显示窗口数量，与 conn_fds 和 windows 数组长度匹配
* @return :void
*/
void TRRO_setWindows(int* conn_fds, WindowIdType * windows, int num);

/*
* @name :  TRRO_disconnect
* @brief : 关闭conn_fds 对应的视频连接
* @input : conn_fds 要关闭视频连接对应的视频接收句柄数组
*          fd_num conn_fd数组长度
* @return : 成功 1 失败 <= 0
*/
int TRRO_disconnect(int* conn_fds, int fd_num);


/*
* @name :  TRRO_disconnectAll
* @brief : 关闭所有视频连接
* @input : void
* @return : 成功 1 失败 <= 0
*/
int TRRO_disconnectAll();

/*
* @name :  TRRO_SetRenderConfig
* @brief : 设置接收流句柄对应的内部渲染模式, 仅内部渲染时使用
* @input : conn_fds 要设置渲染模式的接收视频流句柄数组
*          rotation 旋转角度 数组 rotation 为正顺时针旋转，rotation为负 逆时针旋转
*          scale 分辨率匹配模式数组 0 窗口拉伸， 1 保持原比例
*          config 预留渲染配置数组 0x00000XYZ X为1~2时开启夜视不同等级 推荐为2，Y为1时为开启超分模式，Z为1时为开启镜像渲染
*          num  配置的内部渲染流数量，与输入数组长度匹配
* @return : 成功 1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_SetRenderConfig(int *conn_fds, int *rotation, int *scale, int *config, int num);

/*
* @name :  TRRO_fieldDeviceEncodeConfig
* @brief : 更新现场设备目标视频流编码参数
* @input : gwid 现场设备id
*          streams_id 目标视频流编号
*          encode_config 待更新的编码参数，JSON 格式字符串，缺省字段将保持当前值不进行更新。 下面是更新支持的编码参数示意
*  {
*       "fps": 30,
*       "encode_width": 1920,
*       "encode_height": 1080,
*       "bps": 3000,
*       "min_fps": 30,
*       "min_bps": 1800,
*       "force_min": 0,
*       "min_width": 1920 
*  }
*/
extern "C" TRRO_EXPORT int TRRO_fieldDeviceEncodeConfig(const char* gwid, int streams_id, const char* encode_config);


/*
* @name :  TRRO_startMediaPush
* @brief : 开启rtmp/rtsp转推，调用TRRO_stopMediaPush停止，当调用connect/disconnect函数后conn_fd连接的视频流发生切流或断开时，也会自动停止推流，需要重新start才能推流
* @input : conn_fd     接收视频流的句柄标识
*          path        推流地址
* @return : 成功 1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_startMediaPush(int conn_fd, const char* path);


/*
* @name :  TRRO_stopMediaPush
* @brief : 停止rtmp/rtsp转推
* @input : conn_fd     接收视频流的句柄标识
* @return : 成功 1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_stopMediaPush(int conn_fd);


extern "C" TRRO_EXPORT void TRRO_registerVideotimeCallback(void* context, TRRO_onVideotimeReport * callback);
/*
* @name :  TRRO_onVideotimeReport (depreciated)
* @brief : 视频帧采集时间戳回调, 旧接口，建议使用 onAllLatencyReport 接口获取
* @input : context     回调上下文指针, 返回注册回调函数时传入的 context
*          gwid        视频来源现场设备 ID 
*          conn_fd       对应视频流接收句柄 
*          videotime   当前视频帧的现场设备采集时间戳 
* @return : void
*/
typedef void STD_CALL TRRO_onVideotimeReport(void* context, const char* gwid, int conn_fd, long long videotime);

extern "C" TRRO_EXPORT void TRRO_registerRemoteFrameCallback(void* context, TRRO_onRemoteFrameData * callback, int frame_type = 0);

/*
* @name :  TRRO_onRemoteFrameData
* @brief : 原始视频图像帧回调
* @input : context     回调上下文指针, 返回注册回调函数时传入的 context
*          gwid        视频帧的来源现场设备 ID
*          stream_id   视频帧的来源现场设备流 ID
*          conn_fd     接收视频流的句柄标识
*          data        视频图像帧数据，数据格式为YUVI420，可通过I4202ARGB接口转 ARGB
*          width       视频帧宽
*          height      视频帧高
*          videotime   当前视频帧的现场设备采集时间戳
* @return : void
*/
typedef void STD_CALL TRRO_onRemoteFrameData(void* context, const char* gwid, int stream_id, int conn_fd, const char* data, int width, int height, long long videotime);


extern "C" TRRO_EXPORT void TRRO_registerRemoteEncodedFrameCallback(void* context, TRRO_onRemoteEncodedFrameData* callback);

enum TrroCodec {
  Trro_H264 = 0,
  Trro_H265 = 1,
  Trro_AV1 = 2,
};


/*
 * @name :  TRRO_onRemoteEncodedFrameData
 * @brief : 编码视频图像帧回调
 * @input : context       回调上下文指针, 返回注册回调函数时传入的 context
 *          gwid          视频帧的来源现场设备 ID
 *          stream_id     视频帧的来源现场设备流 ID 
 *          conn_fd       接收视频流的句柄标识
 *          data          编码的视频图像帧数据
 *          len           编码的视频图像帧的长度
 *          trro_codec    编码的 codec 类型
 *          is_key_frame  是否是关键帧
 *          videotime     当前视频帧的现场设备采集时间戳
 * @return : void
 */
typedef void STD_CALL TRRO_onRemoteEncodedFrameData(void* context, const char* gwid, int stream_id, int conn_fd,
                                                    const char* data, int len, TrroCodec trro_codec, bool is_key_frame,
                                                    long long videotime);


extern "C" TRRO_EXPORT void TRRO_registerRemoteEncodedFrameCallback(void* context, TRRO_onRemoteEncodedFrameData* callback);

enum TrroCodec {
  Trro_H264 = 0,
  Trro_H265 = 1,
  Trro_AV1 = 2,
};


/*
 * @name :  TRRO_onRemoteEncodedFrameData
 * @brief : 编码视频图像帧回调
 * @input : context       回调上下文指针, 返回注册回调函数时传入的 context
 *          gwid          视频帧的来源现场设备 ID
 *          stream_id     视频帧的来源现场设备流 ID 
 *          conn_fd       接收视频流的句柄标识
 *          data          编码的视频图像帧数据
 *          len           编码的视频图像帧的长度
 *          trro_codec    编码的 codec 类型
 *          is_key_frame  是否是关键帧
 *          videotime     当前视频帧的现场设备采集时间戳
 * @return : void
 */
typedef void STD_CALL TRRO_onRemoteEncodedFrameData(void* context, const char* gwid, int stream_id, int conn_fd,
                                                    const char* data, int len, TrroCodec trro_codec, bool is_key_frame,
                                                    long long videotime);



/*
* @name :  TRRO_sendControlData
* @brief : 向现场设备发送控制数据
* @input : gwid     目标现场设备 ID
*          msg      发送消息，二进制透传
*          len      消息长度  
*          qos      消息传输qos  0:不可靠传输 1:可靠传输
* @return : 成功 1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_sendControlData(const char* gwid, const char* msg, int len, int qos = 0);


extern "C" TRRO_EXPORT void TRRO_registerReportDataCallback(void* context, TRRO_onReportData * callback);

/*
* @name :  TRRO_onReportData
* @brief : 接收来自现场设备信息回调
* @input : context     回调上下文指针, 返回注册回调函数时传入的 context
*          gwid        消息来源现场设备 ID 
*          msg         消息, 二进制透传
*          len         消息长度
*          qos         消息来源传输 qos， 0:不可靠传输, 1:可靠传输
* @return : void
*/
typedef void STD_CALL TRRO_onReportData(void* context, const char* gwid, const char* msg, int len, int qos);

//操控权限
enum TrroPermission {
    kPermissionGuest = 0,
    kPermissionMaster = 1,
};

/*
* @name : TRRO_requestPermission
* @brief : 向网关发出权限请求，网关会反馈TRRO_OnOperationPermissionState 更新权限
* @input : gwid         目标设备 ID
*          permisson    参考结构体 TrroPermission
* @return : 成功1 失败 <= 0
*/
extern "C" TRRO_EXPORT int TRRO_requestPermission(const char* gwid, int permisson);


extern "C" TRRO_EXPORT void TRRO_registerOnOperationPermissionState(void* context, TRRO_OnOperationPermissionState* callback);


//操控权限
enum TrroPermission {
    kPermissionGuest = 0,
    kPermissionMaster = 1,
};

/*
* #name :   TRRO_OnOperationPermissionState
* @brief :  回调现场设备操控权限状态通知
* @input :  context             回调上下文指针, 返回注册回调函数时传入的 context
*           field_devid         来源现场设备 ID
*           self_permission     本设备当前的操控权限，参考 TrroPermission， 0 是 guest，只有观看权限， 1是 master，拥有完全控制权限
*           master_devid        拥有 master 权限的远端设备 ID
* @return : void
*/
typedef void STD_CALL TRRO_OnOperationPermissionState(void* context, const char* field_devid, int self_permission, const char* master_devid);


extern "C" TRRO_EXPORT void TRRO_registerLatencyCallback(void* context, TRRO_onLatencyReport * callback);
extern "C" TRRO_EXPORT void TRRO_registerAllLatencyCallback(void* context, TRRO_onAllLatencyReport * callback);

/*
* @name :  TRRO_onLatencyReport (depreciated)
* @brief : 视频时延回调, 旧接口，建议使用onAllLatencyReport接口获取
* @input : context     回调上下文指针, 返回注册回调函数时传入的context
*          gwid        视频来源现场设备id 
*          conn_fd     对应视频流接收句柄 
*          latency     返回视频上行时延ms 
* @return : void
*/
typedef void STD_CALL TRRO_onLatencyReport(void* context, const char* gwid, int conn_fd, long long latency);


/*
* @name :  TRRO_onAllLatencyReport (Recommended)
* @brief : 时延回调
* @input : context     回调上下文指针, 返回注册回调函数时传入的 context
*          gwid        视频来源现场设备 ID 
*          conn_fd     对应视频流接收句柄 
*          latency1    均值估计视频传输时延ms
*          latency2    均值估计视频传输时延ms
*          videotime   当前视频帧的现场设备采集时间戳
*          rcct        控制信道往返时延ms, 等于控制上行延迟+控制下行延迟 
* @return : void
*/
typedef void STD_CALL TRRO_onAllLatencyReport(void* context, const char* gwid, int conn_fd, long long latency1, long long latency2, long long videotime, int rcct);


extern "C" TRRO_EXPORT int TRRO_registerSignalStateCallback(void *context, TRRO_onSignalState *callback);

/**
 * SignalState 信令连接状态枚举
 */
enum SignalState {
    kTrroReady = 0, /**< 首次连接建立成功 */
    kTrroLost = 1,  /**< 连接断开，内部会进行自动重连 */
    kTrroReup = 2,  /**< 自动重连成功 */
    kTrroKickout = 3,  /**< 被同名用户剔除 */
    kTrroAuthFailed = 4,  /**< 用户名或者密码错误 */
};

/**
* @name TRRO_onSignalState
* @brief 信令连接状态回调
* @param[in]     context        上下文指针
* @param[in]     state          信令连接状态，参考枚举SignalState
* @return void
*/
typedef void TRRO_onSignalState(void *context, SignalState state);


extern "C" TRRO_EXPORT void TRRO_registerOnState(void* context, TRRO_OnState * callback);

//视频连接状态
enum TrroState {
    kDisconnect = 0,
    kConnecting = 1,
    kConnected = 2,
    kDisconnecting = 3,
};

/*
* @name :  TRRO_OnState
* @brief : 视频流连接状态回调
* @input : context     回调上下文指针, 返回注册回调函数时传入的 context
*          gwid        视频帧的来源现场设备 ID 
*          stream_id   视频帧的来源现场设备流 ID
*          conn_fd     接收视频流的句柄标识
*          state       视频流连接状态，对应 TrroState 状态
* @return : void
*/
typedef void STD_CALL TRRO_OnState(void* context, const char* gwid, int stream_id, int conn_fd, int state);