1. 功能介绍
2. 使用流程
- 基本使用流程
3. 接口参考
- 接口列表
- 接口描述
4. 数据结构
- 数据结构列表
5. 注意事项

1. 功能介绍

借助微信小程序音视频通话的能力，开发者可以通过小程序框架，实现设备和手机微信端的一对一音视频通话，满足实时触达场景，提升通话体验。

2. 使用流程

使用前请适配 include\wmpf\wxvoip_os_impl.h 中的相关接口，并确保所有接口均可正常工作
文件系统要求提供8KB的可用空间用于存放密钥（以FAT32文件系统，簇大小4KB估算，不含FAT表）
文件系统要求断电不丢失可持久化存储，不得使用 RAMFS 等断电丢失的文件系统
本模块依赖 av 模块，需在 av 模块后初始化，iv_avt_notify_cb 回调函数收到 IV_AVT_EVENT_P2P_PEER_READY 事件后方可进行呼叫
设备端使用前请调用 iv_avt_voip_activate_license_v2 （或云API）进行激活，未激活情况下使用会返回-9或其他错误码（量产设备建议调用云API进行批量激活，云API说明 https://cloud.tencent.com/document/product/1081/106587）
设备激活后请在微信小程序中订阅，未订阅情况下使用会返回-9或其他错误码

基本使用流程

旧接口已停止维护，此处以v2接口为例

int code = 0;
// 依次初始化必要的功能模块
iv_sys_init(...);
iv_dm_init(...);
iv_avt_init(...);
code = iv_avt_voip_init_v2(type, data_path, model_id, wxa_appid)；
if (code) {
    return code;
}

// 若未使用云API激活设备，可调用 iv_avt_voip_activate_license_v2 进行激活
code = iv_avt_voip_activate_license_v2(type);
if (code) {
    return code;
}

// -------- 呼叫流程开始 --------

// iv_avt_notify_cb 回调函数收到 IV_AVT_EVENT_P2P_PEER_READY 事件后方可进行后续呼叫流程
if (!iv_avt_voip_is_busy_v2()) {
    // 非占线情况下即可开始呼叫，该接口为阻塞接口，呼叫成功后微信会弹出语音通话界面
    iv_avt_voip_call_v2(type, open_id, v_info, caller_camera_switch, callee_camera_switch);
}
else {
    // 如果本机已在通话中可以主动挂断；如有其他用户占线请稍后重试
    iv_avt_voip_hang_up_v2();
}

while (1) {
    // 呼叫成功后会触发 iv_avt_start_real_play_cb 等多个回调函数，之后便可以收发音视频数据
    // 详细使用方法请查阅音视频传输及对讲模块文档
    iv_avt_send_stream();
}
// 通话结束后请主动挂断，对方挂断会收到 iv_avt_recv_command_cb 回调函数发来的信令
iv_avt_voip_hang_up_v2();
// -------- 呼叫流程结束 --------

// 不再使用请依次销毁相关模块，长带电设备不必销毁，重复上述呼叫流程即可
iv_avt_voip_exit_v2();
iv_avt_exit();
iv_dm_exit();
iv_sys_exit();

3. 接口参考

接口列表

该功能模块提供以下接口

iv_avt_voip_init() voip功能初始化（停止维护，请使用v2接口）
iv_avt_voip_is_registered() 检查设备是否注册（停止维护，请使用v2接口）
iv_avt_voip_register() 设备注册（停止维护，请使用v2接口）
iv_avt_voip_exit() voip功能关闭（停止维护，请使用v2接口）
iv_avt_voip_call() voip呼叫（停止维护，请使用v2接口）
iv_avt_voip_hang_up() voip挂断（停止维护，请使用v2接口）
iv_avt_voip_is_busy() voip是否占线（停止维护，请使用v2接口）
iv_avt_voip_init_v2() voip功能初始化
iv_avt_voip_exit_v2() voip功能关闭
iv_avt_voip_call_v2() voip呼叫
iv_avt_voip_hang_up_v2() voip挂断
iv_avt_voip_is_busy_v2() voip是否占线
iv_avt_voip_activate_license_v2() 激活设备
iv_avt_voip_get_active_device_info_v2() 获取激活设备信息
iv_avt_voip_get_user_list_v2() 获取微信用户列表

用户需注册以下回调函数

(*iv_avt_voip_update_authorize_status_cb)() 更新用户授权订阅状态通知

接口描述

iv_avt_voip_init

功能描述
voip模块初始化，函数内部会执行鉴权等操作
该接口为阻塞接口，阻塞时长视网络情况而定

函数原型

int iv_avt_voip_init(voip_wxa_type_e type,
                     const char *data_path, const char *model_id,
                     const char *device_id, const char *wxa_appid);

参数说明

参数名称	类型	描述	输入/输出
type	voip_wxa_type_e *	小程序类型	输入
data_path	const char *	voip 自动生成的设置文件存储路径	输入
model_id	const char *	voip model_id	输入
device_id	const char *	voip device_id	输入
wxa_appid	const char *	voip 微信小程序 wxa_appid	输入

返回值

返回值	描述
WXERROR_OK	成功
WXERROR_*	失败，请参考 wx_error_t 对应的错误码
9800001	sn长度不能超过128字节
9800002	sn包含非法字符
9800003	model_id检查不通过

iv_avt_voip_is_registered

功能描述
检测设备是否已经注册
需要在 iv_avt_voip_init 调用完成之后才能调用本函数

函数原型

int iv_avt_voip_is_registered(int *is_reg);

参数说明

参数名称	类型	描述	输入/输出
is_reg	int *	voip 微信小程序绑定 ticket	输出

返回值

返回值	描述
WXERROR_OK	成功
WXERROR_*	失败，请参考 wx_error_t 对应的错误码

int iv_avt_voip_register

功能描述
注册设备
该接口为阻塞接口，阻塞时长视网络情况而定
新设备初次使用或清理 data_path 后需要调用一次此接口进行注册
绑定成功后 data_path 路径下会产生大小不为0的密钥文件，请勿删除
如需重新绑定（或恢复出厂设置等情况）请删除 data_path 路径下所有文件，并使用新的 ticket 重新绑定
若设备已经注册，则立即返回
若设备未注册或注册数据错误，会再次注册

函数原型

int iv_avt_voip_register(const char *ticket);

参数说明

参数名称	类型	描述	输入/输出
ticket	const char *	voip 微信小程序绑定 ticket，有效期5分钟，获取后请尽快注册	输入

返回值

返回值	描述
WXERROR_OK	成功
WXERROR_*	失败，请参考 wx_error_t 对应的错误码
-10008	snticket 有问题，常见原因是 snticket 过期

iv_avt_voip_exit

功能描述
voip模块去初始化，释放资源

函数原型

void iv_avt_voip_exit();

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
无	无

iv_avt_voip_call

功能描述
发起 voip 呼叫，该接口为阻塞接口，阻塞时长视网络情况而定

函数原型

int iv_avt_voip_call(iv_cm_stream_type_e type, const char *open_id, const char *device_id,
                     const char *model_id, const char *wxa_appid, voip_video_info_s v_info,
                     uint32_t caller_camera_switch, uint32_t callee_camera_switch)

参数说明

参数名称	类型	描述	输入/输出
type	iv_cm_stream_type_e	呼叫类型，支持音视频、或仅音频	输入
open_id	const char *	voip open_id	输入
device_id	const char *	voip device_id	输入
model_id	const char *	voip model_id	输入
wxa_appid	const char *	voip 微信小程序 wxa_appid	输入
v_info	voip_video_info_s	设备端指定收发视频格式信息	输入
caller_camera_switch	uint32_t	主叫端摄像头开关，0关闭，1开启，如果设备端不具备摄像头或不需要开启摄像头，请设置为关闭	输入
callee_camera_switch	uint32_t	被叫端摄像头开关，0关闭，1开启，如果设备端不具备屏幕或不需要查看微信用户的摄像头内容，请设置为关闭	输入

返回值

返回值	描述
-1	groupId 错误
-2	设备 deviceId 错误
-3	voip_id 错误
-4	校园场景支付刷脸模式，voipToken 错误
-5	生成 voip 房间错误
-7	openId 错误
-8	openId 未授权
-9	校园场景支付刷脸模式：openId 不是 userId 的联系人；硬件设备模式：openId 未绑定设备
-12	小程序音视频能力审核未完成，正式版中暂时无法使用
-13	硬件设备拨打手机微信模式，voipToken 错误
-14	手机微信拨打硬件设备模式，voipToken 错误
-15	音视频费用包欠费
-17	voipToken 对应 modelId 错误
-19	openId 与小程序 appId 不匹配。请注意同一个用户在不同小程序的 openId 是不同的
-20	openId 无效
WXERROR_OK	成功
WXERROR_*	正数错误码，请参考 wx_error_t 对应的错误码
IV_ERR_AVT_REQ_CHN_BUSY	占线
IV_ERR_AVT_INPUT_PARAM_INVAILD	初始化失败或未初始化
IV_ERR_AVT_FAILED	其他错误

iv_avt_voip_hang_up

功能描述
用于本机主动挂断 voip 呼叫
对方主动挂断通话时不需要调用此接口

函数原型

int iv_avt_voip_hang_up();

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
IV_ERR_NONE	成功
IV_ERR_*	失败，对应相应错误码

iv_avt_voip_is_busy

功能描述
检查是否占线

函数原型

int iv_avt_voip_is_busy()

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
0	无占线
1	占线

iv_avt_voip_init_v2

功能描述
voip模块初始化，函数内部会执行鉴权等操作
该接口为阻塞接口，阻塞时长视网络情况而定
新设备初次使用或清理 data_path 目录后调用此接口会在 data_path 路径下会产生大小不为0的配置文件，请勿删除
若 data_path 路径下已有配置文件，调用此接口不会重复生成配置文件
如需重新绑定（或开发调试期间更换设备信息、恢复出厂设置等情况）请退出此模块，然后删除 data_path 路径下所有文件，并重新初始化

函数原型

int iv_avt_voip_init_v2(voip_wxa_type_e type, const char *data_path, const char *model_id,
                        const char *wxa_appid, voip_callback_func_s functions);

参数说明

参数名称	类型	描述	输入/输出
type	voip_wxa_type_e *	小程序类型	输入
data_path	const char *	voip 自动生成的设置文件存储路径	输入
model_id	const char *	voip model_id	输入
wxa_appid	const char *	voip 微信小程序 wxa_appid	输入
functions	voip_callback_func_s	回调函数	输入

返回值

返回值	描述
WXERROR_OK	成功
WXERROR_*	失败，请参考 wx_error_t 对应的错误码
9800001	sn长度不能超过128字节
9800002	sn包含非法字符
9800003	model_id检查不通过

iv_avt_voip_exit_v2

功能描述
voip模块去初始化，释放资源

函数原型

void iv_avt_voip_exit_v2();

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
无	无

iv_avt_voip_call_v2

功能描述
发起 voip 呼叫，该接口为阻塞接口，阻塞时长视网络情况而定

函数原型

int iv_avt_voip_call_v2(iv_cm_stream_type_e type, const char *open_id, voip_video_info_s v_info,
                        uint32_t caller_camera_switch, uint32_t callee_camera_switch)

参数说明

参数名称	类型	描述	输入/输出
type	iv_cm_stream_type_e	呼叫类型，支持音视频、或仅音频	输入
open_id	const char *	被叫微信用户的 open_id	输入
v_info	voip_video_info_s	设备端指定收发视频格式信息	输入
caller_camera_switch	uint32_t	主叫端摄像头开关，0关闭，1开启，如果设备端不具备摄像头或不需要开启摄像头，请设置为关闭	输入
callee_camera_switch	uint32_t	被叫端摄像头开关，0关闭，1开启，如果设备端不具备屏幕或不需要查看微信用户的摄像头内容，请设置为关闭	输入

返回值

返回值	描述
-1	groupId 错误
-2	设备 deviceId 错误
-3	voip_id 错误
-4	校园场景支付刷脸模式，voipToken 错误
-5	生成 voip 房间错误
-7	openId 错误
-8	openId 未授权
-9	校园场景支付刷脸模式：openId 不是 userId 的联系人；硬件设备模式：openId 未绑定设备
-12	小程序音视频能力审核未完成，正式版中暂时无法使用
-13	硬件设备拨打手机微信模式，voipToken 错误
-14	手机微信拨打硬件设备模式，voipToken 错误
-15	音视频费用包欠费（请购买激活码，并正确分配到对应的产品中）
-17	voipToken 对应 modelId 错误
-19	openId 与小程序 appId 不匹配。请注意同一个用户在不同小程序的 openId 是不同的
-20	openId 无效
WXERROR_OK	成功
WXERROR_*	正数错误码，请参考 wx_error_t 对应的错误码
IV_ERR_AVT_REQ_CHN_BUSY	占线
IV_ERR_AVT_INPUT_PARAM_INVAILD	初始化失败或未初始化
IV_ERR_AVT_FAILED	其他错误

iv_avt_voip_hang_up_v2

功能描述
用于本机主动挂断 voip 呼叫
对方主动挂断通话时不需要调用此接口

函数原型

int iv_avt_voip_hang_up_v2();

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
IV_ERR_NONE	成功
IV_ERR_*	失败，对应相应错误码

iv_avt_voip_is_busy_v2

功能描述
检查是否占线

函数原型

int iv_avt_voip_is_busy_v2()

参数说明

参数名称	类型	描述	输入/输出
无	无	无	无

返回值

返回值	描述
0	无占线
1	占线

iv_avt_voip_activate_license_v2

功能描述
激活设备
若未使用云API激活设备，可调用此接口进行激活
云API激活接口 https://cloud.tencent.com/document/product/1081/106587 （其中sn由<ProductId>_<DeviceName>格式拼接而成）

函数原型

int iv_avt_voip_activate_license_v2(voip_activate_type_e type)

参数说明

参数名称	类型	描述	输入/输出
type	voip_activate_type_e	设备类型	输入

返回值

返回值	描述
0	正常
非0值	异常

iv_avt_voip_get_active_device_info_v2

功能描述
获取设备激活信息

函数原型

int iv_avt_voip_get_active_device_info_v2(voip_activate_info_s *info)

参数说明

参数名称	类型	描述	输入/输出
info	voip_activate_type_e *	设备激活信息	输出

返回值

返回值	描述
0	正常
非0值	异常

iv_avt_voip_get_user_list_v2

功能描述
获取已授权订阅微信用户列表
单次最多获取10个用户，超过10个用户请指定 offset 并分多次获取
当设备被分享给多个用户，且其他用户也授权订阅成功后，该接口可查询到所有授权订阅用户的 open_id，设备端可对某个指定用户发起呼叫

函数原型

int iv_avt_voip_get_user_list_v2(int32_t offset, int32_t limit, char openid_list[][VOIP_MAX_ID_LEN])

参数说明

参数名称	类型	描述	输入/输出
offset	int32_t	偏移量	输出
limit	int32_t	单次获取用户数	输出
openid_list	char (*)[VOIP_MAX_ID_LEN]	用户openid列表，必须大于等于limit	输出

返回值

返回值	描述
大于等于0	用户总数
小于0	异常

iv_avt_voip_update_authorize_status_cb

功能描述
更新用户授权订阅状态通知，当用户在微信小程序中订阅此设备时，会通过此回调下发当前订阅用户的 open_id，设备端可使用该 open_id 呼叫对应的用户
当设备被分享其他用户，且其他用户也授权订阅成功后，该接会收到其他用户的 open_id

函数原型

int (*iv_avt_voip_update_authorize_status_cb)(char *open_id, int status)

参数说明

参数名称	类型	描述	输入/输出
open_id	char *	订阅用户的open_id	输入
status	int	0未授权订阅，1已授权订阅	输入

返回值

返回值	描述
0	正常
非0值	异常

4. 数据结构

数据结构列表

云存模块涉及以下数据结构

iv_cm_* 请参考音视频结构公共模块
wxvoip_os_impl_t HAL接口
voip_wxa_type_e 小程序版本
voip_video_info_s voip呼叫的视频格式
voip_activate_type_e 设备激活类型
voip_activate_info_s 设备激活信息
voip_callback_func_s 回调函数

5. 注意事项

本模块依赖av模块内的音视频传输接口，请按顺序初始化 iv_sys_init, iv_dm_init, iv_avt_init, iv_avt_voip_init
呼叫前前检查是否占线，占线时无法发起呼叫。如果本机已在通话中可以主动挂断后发起新的呼叫；如有其他用户占线请稍后重试
iv_avt_voip_call 呼叫成功后会触发 av 模块中的接口，详细内容请参考 av 模块文档
当对方出现挂断、占线等情况时，iv_avt_recv_command_cb 回调函数内会收到 IV_AVT_COMMAND_CALL_XXX 的信令，用户可根据实际情况处理相关信令
对方正常挂断设备端会先通过 iv_avt_recv_command_cb 回调收到 IV_AVT_COMMAND_CALL_HANG_UP 信令，之后触发 iv_avt_stop_real_play_cb 回调
当网络异常导致挂断时设备端无法收到 IV_AVT_COMMAND_CALL_HANG_UP 信令，只会触发 iv_avt_stop_real_play_cb 回调

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TWECALLV2文档说明.md

TWECALLV2文档说明.md

1. 功能介绍

2. 使用流程

基本使用流程

3. 接口参考

接口列表

接口描述

iv_avt_voip_init

iv_avt_voip_is_registered

int iv_avt_voip_register

iv_avt_voip_exit

iv_avt_voip_call

iv_avt_voip_hang_up

iv_avt_voip_is_busy

iv_avt_voip_init_v2

iv_avt_voip_exit_v2

iv_avt_voip_call_v2

iv_avt_voip_hang_up_v2

iv_avt_voip_is_busy_v2

iv_avt_voip_activate_license_v2

iv_avt_voip_get_active_device_info_v2

iv_avt_voip_get_user_list_v2

iv_avt_voip_update_authorize_status_cb

4. 数据结构

数据结构列表

5. 注意事项

Files

TWECALLV2文档说明.md

Latest commit

History

TWECALLV2文档说明.md

File metadata and controls

1. 功能介绍

2. 使用流程

基本使用流程

3. 接口参考

接口列表

接口描述

iv_avt_voip_init

iv_avt_voip_is_registered

int iv_avt_voip_register

iv_avt_voip_exit

iv_avt_voip_call

iv_avt_voip_hang_up

iv_avt_voip_is_busy

iv_avt_voip_init_v2

iv_avt_voip_exit_v2

iv_avt_voip_call_v2

iv_avt_voip_hang_up_v2

iv_avt_voip_is_busy_v2

iv_avt_voip_activate_license_v2

iv_avt_voip_get_active_device_info_v2

iv_avt_voip_get_user_list_v2

iv_avt_voip_update_authorize_status_cb

4. 数据结构

数据结构列表

5. 注意事项