双人互动白板会话功能

通过阅读本章节,您将快速了解双人互动白板的相关功能,并且能通过本章节中介绍的流程和接口快速搭建一个双人互动白板会话。双人互动白板也称点对点互动白板,参与互动白板的共有两方,按照发起会话与接收会话区分为主叫与被叫角色。SDK提供点对点互动白板从发起会话建立会话会话互动解散会话整个过程的能力,包括呼叫/接收、发送白板数据、结束白板等基础能力接口与异常流程控制与回调。 考虑到白板使用场景与音频使用场景强关联,双人互动白板中包含语音通道(可选)更方便快捷满足简单白板的场景,需要注意的是语音通道全局只能有一个,并且与音视频通话和互动直播功能互斥。

sequenceDiagram participant 主叫 participant 被叫 主叫-->被叫:Step1:建立实时会话 主叫->>被叫:主叫发起实时会话请求(nim_rts_start) 被叫->>被叫:被叫收到实时会话请求回调(nim_rts_start_notify_cb_func) 被叫->>主叫:被叫响应实时会话请求(nim_rts_ack) 主叫 ->>主叫:主叫收到被叫实时会话响应回调(nim_rts_ack_notify_cb_func) 主叫-->被叫:Step2:实时会话过程 loop 实时会话 主叫->>被叫: 发送实时会话数据(nim_rts_send_data) 被叫->>主叫:实时会话数据回调(nim_rts_rec_data_cb_func) 主叫-->>被叫: [可选]发送实时会话控制指令(nim_rts_control) 被叫-->>主叫: [可选]发送实时会话控制指令(nim_rts_control) 主叫->>主叫:实时会话状态反馈回调 end 主叫-->被叫:Step3:结束实时会话 主叫->>被叫:结束实时会话(nim_rts_hangup) 被叫->>主叫:对方结束实时会话回调(nim_rts_hangup_notify_cb_func)

流程中涉及到的API介绍如下:

主叫发起实时会话请求

API介绍

创建rts会话,允许用户发起多个会话,并可以指定是否带有音频通道。音频通道的会话必须初始化音视频能力,并只允许存在一个。在需要音频通话时,需要打开麦克风和播放器。

API原型

参数说明

参数 类型 说明
channel_type int 会话类型,见NIMRtsChannelType,其中如果是单纯的tcp通道填1,如果需要附加音频能力,填5(kNIMRtsChannelTypeTcp+kNIMRtsChannelTypeVchat)
uid string 被邀请者的id
info struct 点对点白板扩展参数
cb function 回调函数
参数 类型 说明
channelType int 会话类型,见NIMRtsChannelType,其中如果是单纯的tcp通道填1,如果需要附加音频能力,填5(kNIMRtsChannelTypeTcp+kNIMRtsChannelTypeVchat)
uid string 被邀请者的id
info object 点对点白板扩展参数
startResHandler function 回调函数
参数 类型 说明
channel_type int 会话类型,见NIMRtsChannelType,其中如果是单纯的tcp通道填1,如果需要附加音频能力,填5(kNIMRtsChannelTypeTcp+kNIMRtsChannelTypeVchat)
uid string 被邀请者的id
json_extension string 点对点白板扩展参数
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
枚举定义 说明
kNIMRtsChannelTypeNone 0 无通道
kNIMRtsChannelTypeTcp 1 tcp通道
kNIMRtsChannelTypeUdp 2 udp通道 暂不支持
kNIMRtsChannelTypeVchat 4 音视频通道
键常量名 键常量值 值类型 说明
kNIMRtsSessionId session_id string 发起会话的标识id,用于在关闭时做对应标识。Ack有效
kNIMRtsVChatCustomAudio custom_audio int 是否用自主的音频数据 >0表示是 Ack有效
kNIMRtsDataRecord data_record int 是否需要服务器录制白板数据 >0表示是 Ack有效
kNIMRtsAudioRecord audio_record int 是否需要服务器录制音频数据 >0表示是 Ack有效
kNIMRtsApnsText apns string 推送用的文本
kNIMRtsCreateCustomInfo custom_info string 自定义数据,透传给被邀请方
kNIMRtsPushEnable push_enable int 是否需要推送 >0表示是 默认是
kNIMRtsNeedBadge need_badge int 是否需要角标计数 >0表示是 默认是
kNIMRtsNeedFromNick need_nick int 是否需要推送昵称 >0表示是 默认是
kNIMRtsApnsPayload payload string JSON格式,推送payload
kNIMRtsSound sound string 推送声音
kNIMRtsKeepCalling keepcalling int 是否强制持续呼叫(对方离线也会呼叫),1表示是,0表示否。默认是

返回值说明

无返回值。
键常量名 键常量值 值类型 说明
kNIMRtsChannelId channel_id int64 通话的通道id

示例

    public void RtsTest()
    {
        NIM.NIMRts.RtsStartInfo info = new NIM.NIMRts.RtsStartInfo();
        info.ApnsText = "123";
        info.CustomInfo = "456";
        RtsAPI.Start((NIM.NIMRts.NIMRtsChannelType.kNIMRtsChannelTypeTcp | NIM.NIMRts.NIMRtsChannelType.kNIMRtsChannelTypeVchat), _peerId, info,
            (code, sessionId, channelType, uid) =>
            {
                this.InvokeOnMainThread(() =>
                {
                    if (code == 200)
                    {
                        MessageBox.Show("邀请已发送,等待对方加入");
                    }
                    else
                    {
                        MessageBox.Show("邀请失败:" + ((NIM.ResponseCode)code).ToString());
                    }
                });
            });
    }     

被叫收到实时会话请求回调

API介绍

注册全局的收到实时白板通话请求回调,建议在sdk初始化完成后注册。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记,用于之后操作对应
channelType int 会话类型,见NIMRtsChannelType,其中如果是单纯的tcp通道填1,如果需要附加音频能力,填5(kNIMRtsChannelTypeTcp+kNIMRtsChannelTypeVchat)
uid string 被邀请者的id
customInfo string 扩展信息
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

被叫响应实时会话请求

API介绍

被邀请者回复邀请接口。如果是音频通道的会话必须初始化音视频能力,并只允许存在一个。在需要音频通话时,需要打开麦克风和播放器。

API原型

参数说明

参数 类型 说明
session_id string 本地的一个通话标记
channel_type int 会话类型
accept bool 是否接起
data_record bool 服务器白板数据录制参数
audio_record bool 服务器音频数据录制参数
cb function 回调函数
参数 类型 说明
sessionId string 本地的一个通话标记
channelType int 会话类型
accept bool 是否接起
info object 点对点白板扩展参数
ackResHandler function 回调函数
参数 类型 说明
session_id string 本地的一个通话标记
channel_type int 会话类型
accept bool 是否接起
json_extension string 点对点白板扩展参数
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

主叫收到被叫实时会话响应回调

API介绍

注册全局收到被邀请者的回复结果接口。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记
channelType int 会话类型
accept bool 对方是否接起
uid string 对方id
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

实时会话状态反馈回调

API介绍

在会话邀请接起后,双方通过连接状态和成员变化接口得知会话状态。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记
channelType int 会话类型
type int 成员进出状态
uid string 对方id
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
枚举定义 说明
kNIMRtsMemberStatusJoined 0 成员进入
kNIMRtsMemberStatusLeaved 1 成员退出

返回值说明

无返回值。

键常量名 键常量值 值类型 说明
kNIMRtsRecordFile record_file string 录制的文件名(服务器开启录制时有效,音视频类型时为音频文件名)
kNIMRtsVideoRecordFile video_record_file string 录制的视频文件名(服务器开启录制时有效)
kNIMRtsLeaveType leave_type int 客户端类型NIMRtsMemberLeftType
枚举定义 说明
kNIMRtsMemberLeftTimeout -1 成员超时掉线
kNIMRtsMemberLeftNormal 0 成员离开

示例

发送实时会话数据

发送数据,暂时支持tcp通道,建议发送频率在20Hz以下。

API原型

参数说明

参数 类型 说明
session_id string 本地的一个通话标记
channel_type int 会话类型,暂时只支持kNIMRtsChannelTypeTcp
data string tcp数据流
uid string 指定发送某人,不填则群发
参数 类型 说明
sessionId string 本地的一个通话标记
channelType int 会话类型
data IntPtr 数据指针
size int 数据长度
参数 类型 说明
session_id string 本地的一个通话标记
channel_type int 会话类型
accept bool 是否接起
data char* 数据指针
size int 数据长度
json_extension string 扩展参数kNIMRtsUid
键常量名 键常量值 值类型 说明
kNIMRtsUid uid string 用户账号uid

返回值说明

无返回值。

示例

特殊说明

白板数据当遇到网络异常时不能保证对方肯定收到,对需要高保障的数据,建议用户自己用数据流做回执保证。

收到实时会话数据回调

API介绍

收到其他人发给我的白板数据。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
callback function 回调函数
sessionId string 本地的一个通话标记
channelType int 会话类型
uid string 对方id
data IntPtr 数据指针
size int 数据长度
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

    void OnReceiveRtsData(string sessionId, int channelType, string uid, IntPtr data, int size)
    {
        var content = Marshal.PtrToStringAnsi(data, size);
        //解析content,处理逻辑
    }
    void RegisterRtsCallback()
    {
        NIM.RtsAPI.SetReceiveDataCallback(OnReceiveRtsData);
    }

发送实时会话控制指令

API介绍

发送用户控制指令,允许在通话发起后发送一些自定义的通知。

API原型

参数说明

参数 类型 说明
session_id string 本地的一个通话标记
info string 自定义数据
cb function 回调函数
参数 类型 说明
sessionId string 本地的一个通话标记
info string 自定义数据
controlResHandler function 回调函数
参数 类型 说明
session_id string 本地的一个通话标记
info char* 自定义字符串数据
json_extension string 扩展参数kNIMRtsUid
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
键常量名 键常量值 值类型 说明
kNIMRtsUid uid string 用户账号uid

返回值说明

无返回值。

示例

收到实时会话控制指令

API介绍

注册接收白板的控制指令的回调函数。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记
info string 自定义的控制
uid string 对方id
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

结束实时会话

API介绍

结束会话,清理会话。如果是主动结束,会通知对方。

API原型

参数说明

参数 类型 说明
session_id string 本地的一个通话标记
cb function 回调函数
参数 类型 说明
hangupResHandler function 回调函数
参数 类型 说明
session_id string 本地的一个通话标记
json_extension string 无效扩展
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

对方结束实时会话回调

API介绍

注册收到对方结束会话的通知回调接口。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记
uid string 对方id
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

呼入的实时会话请求已经被该帐号其他端处理回调

API介绍

多端同步接口,注册该账号在其他端处理了的回调通知接口。

API原型

参数说明

参数 类型 说明
cb function 回调函数
参数 类型 说明
cb function 回调函数
sessionId string 本地的一个通话标记
channelType int 会话类型
accept bool 是否接起
client int 客户端类型,见NIMClientType
参数 类型 说明
cb function 回调函数
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
枚举定义 说明
kNIMClientTypeDefault 0 Default, unset
kNIMClientTypeAndroid 1 Android
kNIMClientTypeiOS 2 iOS
kNIMClientTypePCWindows 4 PC Windows
kNIMClientTypeWeb 16 Web
kNIMClientTypeRestAPI 32 RestAPI
kNIMClientTypeMacOS 64 Mac

返回值说明

无返回值。

键常量名 键常量值 值类型 说明
kNIMRtsClientType client_type int 客户端类型NIMClientType

示例

设置静音

API介绍

API原型

参数说明

参数 类型 所在函数 说明
muted bool SetAudioMuted(C/C#)
nim_vchat_set_audio_mute(C)
true静音,false不静音。

返回值说明

设置静音接口无返回值。

获取静音状态接口返回静音状态。

示例

开启音频设备

API介绍

启动设备。同一NIMDeviceType下设备将不重复启动,不同的设备会先关闭前一个设备开启新设备。如果需要打开非默认设备,则需要遍历设备,选择需要的设备path。

API原型

参数说明

参数 类型 说明
type enum 设备类型,见NIMDeviceType
device_path string 设备路径对应kNIMDevicePath,如果是kNIMDeviceTypeAudioHook,对应播放器本地全路径。
fps unsigned int 摄像头的采样频率,非摄像头类型设备无效(麦克风采样频率由底层控制,播放器采样频率也由底层控制)。
width(C++) int 摄像头采集宽度期望值,取0则底层选默认值,非摄像头类型设备无效。
height(C++) int 摄像头采集高度期望值,取0则底层选默认值,非摄像头类型设备无效。
StartDeviceInfo(C#) object 启动设备json封装类。
cb(C/C++)/handler(C#) function 结果回调
user_data(C) void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
枚举定义 说明
kNIMDeviceTypeAudioIn 0 麦克风设备
kNIMDeviceTypeAudioOut 1 听筒设备用于播放本地采集音频数据,麦克风试音
kNIMDeviceTypeAudioOutChat 2 听筒设备用于通话音频数据,由kNIMDeviceTypeAudioOut遍历得到设备
kNIMDeviceTypeVideo 3 摄像头
kNIMDeviceTypeSoundcardCapturer 4 声卡声音采集,由kNIMDeviceTypeAudioOut遍历得到设备,得到的数据混音到发送的通话声音中(此模式使用条件苛刻不建议使用)
kNIMDeviceTypeAudioHook 5 伴音,使用本地播放器的启动路径(exe启动文件的全路径),启动第三方播放器并获取音频数据(只允许存在一个进程钩子),只混音到发送的通话声音中

返回值说明

无返回值。

示例

API介绍

结束设备

API原型

参数说明

参数 类型 说明
type enum 设备类型NIMDeviceType
json_extension(C) string 无效的扩展字段。

返回值说明

无返回值。

示例