vdp.h

浏览该文件的文档.

/** \file vdp.h
 *
 * 探鸽双向呼叫设备开发接口.
 */
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "TgCloudApi.h"
 
/** @defgroup vdp_ref 双向呼叫API
 * @{*/
 
/** VDP 初始化.
 * 会调用 TciInit()/TciSetCallback().
 * @param cfg_path  配置文件保存路径，要可读写
 * @param cbs       必需的回调结构
 * @return 0:成功
 */
int TgVdpInit(const char *cfg_path, struct TciCB *cbs);
 
/** 设置p2p命令处理回调, 代替 TciSetCmdHandler().
 * 被叫端(室内机)才会通过此回调接收命令。主叫端通过Caller接口(iCamP2pXxxx)发送命令和接收应答.
 * @param func p2p命令处理回调。
 * @note TgVdpInit()会设置一个内部命令处理回调，只把不处理的命令传给本回调. \n
 *          如果应用很简单，除了音视频外没有额外的交互，可以不提供
 */
void TgVdpSetCmdHandler(TGCMDHANDLER func);
 
/** 开启VDP 服务.
 * @param isBound 设备本地保存的是否绑定的标志。如果为0(没有绑定), 需要走绑定流程
 * @param uuid 设备的 UUID
 * @return 0:成功; 非0:错误码
 */
int TgVdpStart(int isBound, const char *uuid);
 
/** 停止VDP服务, 释放资源
 * 会调用 TciStop()/TciCleanup()
 */
void TgVdpStop();
 
//================================================================
 
struct CalleeEx;
/** 被叫端传过来的命令数据.
 * @param msg 消息头
 * @param len 消息长度
 * @param callee 同回调相匹配的 CalleeEx 结构
 */
typedef void (*RTMSGCALLBACK)(const RTMSG_t *msg, int len, struct CalleeEx *callee);
 
/** 被叫 */
struct CalleeEx {
    int        type;     ///< 被叫类型 @ref CALLTYPE_TANGE 或 @ref CALLTYPE_WEIXIN
    char       *token;   ///< 被叫标识
 
    /** 该值为输出参数.
     * 呼叫被接听后(收到 TVCS_ACCEPTED), hConn为与对端的连接句柄，用于进行更多通信。 \n
     * 该返回值也可能为NULL, 表示无法与对端进行音视频之外的通信。
     *
     * - type = CALLTYPE_TANGE, hConn类型为 HP2PCLT, 可以用来调用 icam_p2p.h 中的接口.
     * - type = CALLTYPE_WEIXIN, hConn = NULL
     */
    void       *hConn;
 
    /** 本回调用于接收对端的音视频之外的数据.
     *  - type = CALLTYPE_TANGE, 用于接收对端通过 TciSendRtMsg(.., RTM_USER, ...) 发过来的 RTM_USER 消息
     *  - type = CALLTYPE_WEIXIN, 不支持
     */
    RTMSGCALLBACK msg_cb;
 
    /** 该值为输出参数.
     * 当status = TVCS_FAILED 时, err 为错误码.
     * 错误码取值同被叫类型有关:
     * 微信呼叫错误范围 -10008, -20~20, 说明在 wx_err.h
     * Tange呼叫错误码在 TgCloudConst.h
     */
    int        err;
 
    /** 用于向回调中传入用户自己的额外数据 */
    void       *pUser;
};
 
/** 呼叫/通话状态 */
enum EVDPCALLSTATE { 
    TVCS_CALLING,         ///< 呼叫中
    TVCS_REJECTED,        ///< 拒接
    TVCS_ACCEPTED,        ///< 接听
    TVCS_TIMEDOUT,        ///< 呼叫超时
    TVCS_REMOTE_HANGUP,   ///< 对端挂断
    TVCS_FAILED,          ///< 呼叫失败
};
/** 呼叫/通话状态回调.
 * @param status 状态 @ref EVDPCALLSTATE
 * @param pCallee status=TVCS_ACCEPTED为被叫指针，其于时候为NULL. \n
 *                注意，这个指针不同于调用 TgVdpCall()时传入的数组元素的地址， \n
 *                因为那个数组会被复制
 * @return  未用到,  Always return 0
 */
typedef int (*TGVDPCALLBACK)(int status, struct CalleeEx *pCallee);
 
/** 呼叫.
 * @param callees 被叫对象数组
 * @param size    数组大小
 * @param timeout 等待时间。单位: 秒.
 *                - 建议此处传0，然后主被叫都通过能力 @ref Feature_CallTime 设置一个相同的超时值, 以保持行为一致。-- 2025/6/5 
 * @param cb      状态回调
 * @return  0: 成功发起呼叫.
 *          非0: 错误码。不能发起呼叫
 *
 * @note 每一次成功的呼叫要调用一次 TgVdpHangup();
 */
int TgVdpCallEx(struct CalleeEx *callees, int size, int timeout, TGVDPCALLBACK cb);
 
/** 结束呼叫或通话. 
 * 对主叫端，可以在调用 TgVdpCall()成功后的任何时候调用本接口, 从而实现 取消呼叫、结束通话、响应对方挂断 的功能. \n
 * 对被叫端，调用本接口实现通话中挂断的功能, 实际调用了TciHangup().
 * @return 0
 * @note 不要在回调里调用
 */
int TgVdpHangup();
 
//================================================================
/** 被叫接听, 等同于 TciAcceptInCall2().
 * @note 不要在回调里调用.
 */
int TgVdpAccept2();
 
/** 被叫拒接, 等同于 TciRejectInCall2().
 * @note 不要在回调里调用
 */
int TgVdpReject2();
 
/**@}*/ //defgroup vdp
 
#ifdef __cplusplus
} /* extern "C" */
#endif