跑通呼叫组件(Windows)
为了方便开发者快速接入音视频通话 2.0,提升应用的研发效率,音视频通话 2.0 和信令产品携手为您打造应用层呼叫组件 NERTCCallkit,组件中集成了音视频通话 2.0 和信令的多项基础功能,全方位提升接入效率。
NERTCCallkit 呼叫组件的 API 接口概览请查看组件概述。
准备工作
- 已在控制台创建应用,并获取了对应的 App Key。
- 已获取安全认证签名 Token,详细操作请参考获取 Token。
- 已根据需求开通相关服务和功能。需开通的服务清单请参考开通相关服务。
- 请确认当前使用的 SDK 版本。NERTCCallkit 组件依赖以下 SDK 版本:
- NERTC SDK 3.7.0 及以上版本。
- IM SDK 8.1.0 及以上版本。
- 信令 SDK 8.1.0 及以上版本。
注意事项
- 针对组件中的回调信息,开发者要做好相应回调数据的上报及存储,以便于后期上线之后排查问题。
- 组件默认使用非安全模式。应用正式上线前,请联系技术支持人员改回安全模式。
组件结构
component 目录中的文件说明如下:
文件夹 | 文件 | 说明 |
---|---|---|
avchat_component.cpp | 组件的文件,其中实现了初始化、呼叫、接听等常见操作。 | |
avchat_component.h | 组件的文件,其中实现了初始化、呼叫、接听等常见操作。 | |
avchat_component_def.h | 组件的文件,其中实现了初始化、呼叫、接听等常见操作。 | |
wrapper | avchat_business_wrapper.cpp | 组件包装类,是为 Demo 中的 Batp 专门包装的 wrapper,不使用 Batp 特性的开发者可忽略。 |
avchat_business_wrapper.h | 组件包装类,是为 Demo 中的 Batp 专门包装的 wrapper,不使用 Batp 特性的开发者可忽略。 |
说明:
- 头文件依赖:组件依赖 NERTC SDK 的一组头文件,位于 Demo 工程的根目录的
nertc_sdk
文件夹下。 - DLL 与 lib 依赖:组件通过隐式链接方式使用 NERTC SDK 的 DLL,包括
nertc_sdk.dll
、nertc_sdk.lib
与SDL2.dll
。- 32 位的 DLL 位于
bin\x86_dlls
目录。 - 64 位的 DLL 位于
bin\x64_dlls
目录。
- 32 位的 DLL 位于
集成组件
- 下载 NERTCCallkit 组件 并解压缩。
找到组件相关代码。
组件所在路径为:
tool_kits/ui_component/g2_kit/component/
。 组件相关文件:avchat_component.h
avchat_component.cpp
avchat_component_def.h
- 将
component
目录添加至 Visual Studio Code 工程中。 其中,wrapper目录可移除。 - 将 NERTC SDK 头文件,即
nertc_sdk
文件夹添加至 VS 工程中。 - 将
DLL
与lib
文件拷贝至自己的运行目录下。 - 在 VS 工程中配置 附加包含目录,添加
nertc_sdk
所在目录 Visual Studio Code 打开文件。 - 在 VS 工程中配置 附加库目录 与 附加依赖项。
配置完毕,此时可以使用
AvChatComponent
类,创建对象、使用音视频 2.0 功能。AvChatComponent
组件有多端统一的事件回调,在avchat_component.h
中定义了一个IAvChatComponentEventHandler
抽象类,您需要继承并实现该类中方法,以实现对事件的响应。Demo 中对该抽象类的实现位于wrapper/ avchat_business_wrapper.cpp
,供您参考。
实现组件基本功能
步骤一 初始化组件
通过以下示例代码初始化 NERTCCallkit 呼叫组件。
void AvChatComponent::setupAppKey(const std::string& key)
{
appKey_ = key;
//创建并初始化engine;
assert(!rtcEngine_);
rtcEngine_ = (nertc::IRtcEngineEx*)createNERtcEngine();
assert(rtcEngine_);
std::string logPath = nbase::UTF16ToUTF8(nbase::win32::GetLocalAppDataDir().append(AVCHAT_LOG_DIR));
nertc::NERtcEngineContext context;
context.app_key = appKey_.c_str();
context.event_handler = this;
context.log_dir_path = logPath.c_str();//AVCHAT_LOG_DIR;
context.log_level = nertc::kNERtcLogLevelDebug;
context.log_file_max_size_KBytes = 0;
//context.log_dir_path = ""
int ret = rtcEngine_->initialize(context);
assert(ret == 0);
/*注册信令回调 */ Signaling::RegOnlineNotifyCb(nbase::Bind(&AvChatComponent::signalingNotifyCb, this, std::placeholders::_1));
}
步骤二 注册组件事件回调
调用 regEventHandler
函数注册组件事件回调。
//注册组件事件回调
void AvChatComponent::regEventHandler(std::shared_ptr<IAvChatComponentEventHandler> compEventHandler)
{
}
步骤三 登录
调用 login 函数完成组件的登录。
NERTCCallkit 呼叫组件与 IM 的 login 方法可共用,如果 IM 登录成功,组件可以不再调用 login 函数。
步骤四 设置 Token
组件默认使用安全模式。如果 tokenHandler 为 nil 表示非安全模式,请联系商务经理开通安全模式。
安全模式下需要获取并传入 Token。详细操作请参考获取 Token。在线上环境中,Token 的获取需要放到您的应用服务端完成,然后由服务器通过安全通道把 Token 传递给客户端。
setTokenService
为抽象方法,主要在 AvChatComponent
类实现,再通过 requestTokenValue()
的callback,在 joinchannel
时设置 Token。
//获取token函数
using GetTokenServiceFunc = std::function<void(int64_t uid, std::function<void(const std::string& token)> onGetToken)>;
/**在线上环境中,token的获取需要放到您的应用服务端完成,然后由服务器通过安全通道把token传递给客户端
Demo中使用的 URL 仅仅是demoserver,不要在您的应用中使用
详细请参考: http://dev.netease.im/docs?doc=server
*/
void setTokenService(GetTokenServiceFunc getTokenService){ getTokenService_ = getTokenService;}
void AvChatComponent::requestTokenValue(int64_t uid)
{
getTokenService_(uid, [=](const std::string token) {
// 请求业务服务器,由业务服务器,调用云信HTTPS接口,获取到Token回传
});
}
步骤五 发起呼叫
参考以下代码发起呼叫:
/*
*userId:呼叫方的accid
*type :呼叫类型,1:音频,2:视频
*cb :呼叫结果回调,会传回错误码,200为success,其他为失败
*/
void AvChatComponent::call(const std::string& userId, AVCHAT_CALL_TYPE type, AvChatComponentOptCb cb)
{
}
步骤六 监听呼叫
实现 IAvChatComponentEventHandler
抽象类中的 onInvited
方法,并调用注册了事件的 hanglder
,即可监听呼叫。
void onInvited(const std::string& invitor,
std::vector<std::string> userIDs,
bool isFromGroup,
int type)
{
//处理呼叫(例如拉起界面,让用户选择接受或者拒绝)
};
virtual void onUserAccept(const std::string& userId) {
//对方接受呼叫,应设置本地画布与远端画布,以便展示视频画面
}
virtual void onUserReject(const std::string& userId) {
//对方拒绝呼叫,应给出UI提示,并关闭视频会话窗口
}
};
步骤七 接听来电
被叫方调用 accept
函数接听来电。
//调用该方法即可接受呼叫,
void AvChatComponent::accept(AvChatComponentOptCb cb)
{
}
步骤七 挂断通话
主叫方和被叫方处于通话中时,调用 hangup
函数可以结束通话。
//调用该方法即可接挂断通话
void AvChatComponent::hangup(AvChatComponentOptCb cb)
{
}
步骤八 获取话单
说明:
- 多人通话默认未封装话单功能。若您需要使用话单,请通过其他方式自行实现。
- 在一对一通话中,若您需要使用话单,请联系销售或技术支持,申请开通话单功能,或通过其他方式自行实现。
正常挂断
通话正常挂断时,Demo 中的实现流程为:
NIMRtcCallStatus
状态变更为NIMRtcCallStatusComplete
。- 调用组件封装方式的挂断之后,服务器会正常下发正常结束的话单。
- 客户端会通过接收消息的回调
OnReceiveMsgCallback
,收到一条类型为kNIMMessageTypeG2NetCall
的attach_消息。 - 对消息进行解析并上报到业务层进行展示。
在正常挂断的情况下,您可以参考 net_call_helper
中 _ParseNetCallContent
方法实现话单功能解析及展示。
异常挂断
异常挂断的情况下,业务层需要主动调用 cancel
方法。
//挂断处理函数
void AvChatComponent::hangup(AvChatComponentOptCb cb)
//处理非正常挂断情况下的话单
void AvChatComponent::handleNetCallMsg(nim_comp::NIMNetCallStatus why)
组件话单由组件内部发送,直接提供给对方,其中包含超时、忙线、拒绝的消息。
组件底层通过调用 send1to1CallRecord
方法实现话单,构建一条消息进行发送。您也可以自行实现该逻辑。
底层实现方式为:
- 调用 SDK 创建消息
CreateG2NetCallMessage
,发送一对一消息 sendTextMessage。 - 通过封装信息之后,发送给对方。
- 对方收到消息解析。
实现 UI 界面
如需快速接入呼叫组件,您可以直接基于我们提供的组件 Demo 进行修改适配,也可以自行实现自定义的 UI 界面。
Demo 说明
Demo 中 的 UI 使用 Duilib 实现,通过 VideoManagerG2
类统一处理组件与 UI 的交互,相关资源如下:
- 代码所在目录:
tool_kits/ui_component/g2_kit/gui
目录。 - 视频窗口的资源文件(xml)目录及文件名:
bin/resources/themes/default/video/
目录中的、videoform_g2.xml
和video_setting_g2.xml
文件。
另外,Demo 中通过 NERTC SDK 的回调函数中取得视频帧的 RGB 数据,并使用 BitmapControlG2::Paint
方法在 UI 框架上绘制画面。完整代码请参考 Demo 中 tool_kits\ui_component\g2_kit\gui\
目录下的 bitmap_control_g2.cpp
和 video_form_g2.cpp
文件。
绘制画面方式
音视频通话 2.0 支持以下两种方式绘制视频画面:
直接传 Windows 窗口句柄,由 NERTC SDK 负责绘制视频画面到窗口句柄上。
这种方式无需开发者绘制画面,能够较快的集成。但视频画面会不断刷新,覆盖其他元素,所以视频画面之上无法覆盖其他界面元素,难以实现复杂的交互设计。
从 NERTC SDK 的回调函数中取得视频帧数据,由开发者将视频帧数据绘制到自己的界面。
这种方式由开发者取回视频帧数据,自行绘制,可实现复杂交互,例如可以在视频画面上覆盖一些按钮、文字等界面元素。但绘制代码较为复杂。
Demo 中采用该方式实现,完整代码请参考 Demo 中
tool_kits\ui_component\g2_kit\gui\
目录下的bitmap_control_g2.cpp
和video_form_g2.cpp
文件。


此文档对你是否有帮助

