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().
 * 对端(只能另一个VDP设备)的请求和应答都通知本回调接收.
 * @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 或 @ref CALLTYPE_EVENT
    /** 被叫标识.
     *  - CALLTYPE_WEIXIN: 为微信用户的 open id
     *  - CALLTYPE_TANGE: 设备的连接token
     *  - CALLTYPE_EVENT: 如果为NULL, 呼叫全部App用户; 如果非空，则为指定App用户的 user id
     */
    char       *token;
 
    /** 该值为输出参数.
     * 呼叫被接听后(收到 TVCS_ACCEPTED), hConn为与对端的连接句柄，可以调用TgVdpSend()来发送数据。 \n
     * 该返回值也可能为NULL, 表示无法与对端进行音视频之外的通信。
     *
     * 仅当 type 为 CALLTYPE_TANGE 或 CALLTYPE_EVENT, hConn 才会非NULL.
     */
    void       *hConn;
 
    /** @deprecated
     * <b><i>从rev.349起统一通过命令处理回调接收, 不再需要此回调</i></b>
     *
     * 本回调用于接收对端的音视频之外的数据.
     *  - 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      状态回调
 * @param whoami  呼叫者标识, 内容自定义。
 * @param bShowMeBeforeAccepted 允许对方接听前看到主叫的视频. 门口机呼叫室内机时可以打开此选项。
 * @return  0: 成功发起呼叫.
 *          非0: 错误码。不能发起呼叫
 *
 * @note 被叫对象数组中可以有多个CALLTYPE_TANGE型，其它最多一个. \n
 *       每一次成功的呼叫要调用一次 TgVdpHangup();
 */
int TgVdpCallEx(struct CalleeEx *callees, int size, int timeout, TGVDPCALLBACK cb, const char *whoami, int bShowMeBeforeAccepted);
 
/** 结束呼叫或通话. 
 * 对主叫端，可以在调用 TgVdpCall()成功后的任何时候调用本接口, 从而实现 取消呼叫、结束通话、响应对方挂断 的功能. \n
 * 对被叫端，调用本接口实现通话中挂断的功能, 实际调用了TciHangup().
 * @return 0
 * @note 不要在回调里调用
 */
int TgVdpHangup();
 
//================================================================
/** 被叫接听, 等同于 TciAcceptInCall2().
 * @note 不要在回调里调用.
 */
int TgVdpAccept2();
 
/** 被叫拒接, 等同于 TciRejectInCall2().
 * @note 不要在回调里调用
 */
int TgVdpReject2();
 
/** 发送请求或应答.
 * 只能对设备发送，目前不支持对小程序发送数据。
 * @param handle 连接句柄. 来自不同地方, 见下面注释
 * @param cmd 命令码。
 *              - 用户可用命令范围为0x9000~0xffff
 *              - 请求的命令码最低位为0
 *              - 应答的命令码为请求命令码最低位置1。
 *
 * @param data 请求或应答的数据
 * @param size 数据长度
 *
 * @note 连接句柄handle的获取规则如下:
 *  - 对主叫端, 当呼叫被接听时, 连接句柄为@ref TVCS_ACCEPTED 状态回调的 struct CalleeEx::handle.
 *  - 对被叫端, 连接句柄为呼入回调(@ref STATUS_INCALL2)的参数 INCALLINFO::tg::ptr
 *  - 对主叫和被叫, 如果不是要主动发送请求, 可以从命令处理回调(@ref TGCMDHANDLER)的第一个参数获取
 *
 *  <b>不要使用 TciSendCmdXxxx 接口来发送 !</b>
 */
int TgVdpSend(void *handle, int cmd, const void *data, size_t size);
 
/** 发送请求 */
#define TgVdpSendReq(handle, cmd, data, size) TgVdpSend(handle, (cmd)&0xfffe, data, size)
 
/** 发送应答 */
#define TgVdpSendResp(handle, cmd, data, size) TgVdpSend(handle, (cmd)|1, data, size)
 
/** 发送状态应答.
 * @param status @ref TCI_OK 或 TCI_E_xxx, 参见 @ref generic_err_code "通用错误码"
 * @param handle 参见 TgVdpSend()
 * @param cmd 请求命令
 */
int TgVdpSendRespStatus(void *handle, int cmd, int status);
 
 
/**@}*/ //defgroup vdp
 
#ifdef __cplusplus
} /* extern "C" */
#endif