多人音视频通话
本章节介绍多人实时音视频通话的相关功能。多人实时音视频通话顾名思义是支持多个人同时进行实时音视频通话,可以选择纯音频模式,或音视频模式。在这里需要明确几个概念: 房间:房间就是用户进行多人实时音视频通话的地方,房间以房间名称为唯一标识,多人房间需要先创建成功后才能加入,当所有用户都离开房间后,可以复用该房间名重新创建。 互动者:互动者是指在多人通话时可以参与互动,可以发言的人,这些用户可以发送上行的音频或视频数据,也可以接收其他互动者下行的音频或视频数据。 观众:观众是指在多人通话时只可以观看的人,没有发言的权限,这些用户只可以接收互动者下行的音频或视频数据,不可以发送上行音频或视频数据。 其中互动者和观众身份可以随时切换。
多人音视频通话流程
预定会议
API介绍
根据房间名,创建一个多人会议房间。创建后的房间需要有人加入后才会实际产生话单。
API原型
NIM_SDK_DLL_API void nim_vchat_create_room(const char *room_name, const char *custom_info, const char *json_extension, nim_vchat_opt2_cb_func cb, const void *user_data)
File:nim_vchat.h
参数说明
参数 | 类型 | 说明 |
---|---|---|
room_name | char* | 房间名 |
custom_info | char* | 自定义信息,所有加入房间的成员都会收到此信息 |
json_extension | char* | Json char* 无效扩展字段 |
cb | function | 回调函数 |
user_data | void* | 无效扩展 |
返回值说明
无返回值。
示例
void nim_vchat_create_room_callback(int code, int64_t channel_id, const char *json_extension, const void *user_data)
{
printf("nim_vchat_create_room code->%d,channel_id->%lld,json_extension->%s\n", code, channel_id, json_extension);
}
void test_crate_room(char* room_name)
{
char*custom_info = "";
char *json_extension = "";
nim_vchat_create_room(room_name, custom_info, json_extension, nim_vchat_create_room_callback, NULL);
}
特殊说明
返回错误码中417说明已经存在同名的房间,如果是目标房间议,则可以直接走后面流程加入此房间。如果不是希望创建的目标房间,则需要重新设定房间名后再创建。
加入会议
API介绍
加入一个房间。所有音视频相关通话都是互斥,只允许存在一个,并且加入前必选预先创建房间。
API原型
NIM_SDK_DLL_API bool nim_vchat_join_room(enum NIMVideoChatMode mode, const char *room_name, const char *json_extension, nim_vchat_opt2_cb_func cb, const void *user_data)
File:nim_vchat.h
参数说明
参数 | 类型 | 说明 |
---|---|---|
mode | enum | 音视频通话类型,见nim_vchat_def.h |
room_name | char* | 房间名 |
json_extension | char* | Json char* 扩展,音视频通话的扩展参数设置 |
cb | function | 结果回调 |
user_data | void* | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理! |
示例
void nim_vchat_join_room_callback(int code, int64_t channel_id, const char *json_extension, const void *user_data)
{
printf("nim_vchat_join_room code->%d,channel_id ->%lld,json_extension->%s\n", code, channel_id, json_extension);
if (code == 200)
{
//success
}
}
void test_join_room(char* room_name)
{
test_nim_vchat_join_room(kNIMVideoChatModeVideo, room_name,"", nim_vchat_join_room_callback, NULL);
}
离开会议
API介绍
需要在结束时调用,用于底层挂断和清理数据。
API原型
NIM_SDK_DLL_API void nim_vchat_end(const char *json_extension)
File:nim_vchat.h
参数说明
参数 | 类型 | 说明 |
---|---|---|
json_extension | char* | Json char* 扩展,kNIMVChatSessionId |
示例
nim_vchat_end("");//断开通话
用户进出会议通知
API介绍
在连接建立后,如果已有成员在通话中,或新进来的成员都会通过此回调通知。有成员离开也通过此回调,并告诉是正常离开还是超时离开,超时离开代表本地超时未收到对端数据,可能对方网络异常也可能是本地网络异常。
API原型
typedef void (*nim_vchat_cb_func)(enum NIMVideoChatSessionType type, int64_t channel_id, int code, const char *json_extension, const void *user_data)
NIMVideoChatSessionType::kNIMVideoChatSessionTypePeopleStatus
File:nim_vchat_def.h
参数说明
参数 | 类型 | 说明 |
---|---|---|
type | enum | 回调类型kNIMVideoChatSessionTypePeopleStatus |
channel_id | int64_t | 频道id |
code | int | 状态码,对应NIMVideoChatSessionStatus |
json_extension | char* | Json char* 扩展,返回kNIMVChatUid,如果是离开带kNIMVChatStatus对应NIMVideoChatUserLeftType |
user_data | void* | 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
示例
void nim_vchat_cb(enum NIMVideoChatSessionType type, int64_t channel_id, int code, const char *json_extension, const void *user_data)
{
if (code == 200)
{
switch (type)
{
case kNIMVideoChatSessionTypeStartRes://创建通话结果
break;
case kNIMVideoChatSessionTypeInviteNotify://通话邀请
break;
case kNIMVideoChatSessionTypeCalleeAckRes://确认通话,接受拒绝结果
break;
case kNIMVideoChatSessionTypeCalleeAckNotify://确认通话,接受拒绝通知
break;
case kNIMVideoChatSessionTypeControlRes://NIMVChatControlType 结果
break;
case kNIMVideoChatSessionTypeControlNotify://NIMVChatControlType 通知
break;
case kNIMVideoChatSessionTypeConnect://通话中链接状态通知
break;
case kNIMVideoChatSessionTypePeopleStatus://通话中成员状态
break;
case kNIMVideoChatSessionTypeNetStatus://通话中网络状态
break;
case kNIMVideoChatSessionTypeHangupRes://通话挂断结果
break;
case kNIMVideoChatSessionTypeHangupNotify://通话被挂断通知
break;
case kNIMVideoChatSessionTypeSyncAckNotify://通话接听挂断同步通知
break;
default:
break;
}
}
}
会议发生了错误
API介绍
当房间发生异常,统一返回连接错误信息,和开始时连接成功及连接失败是同一个回调函数。
API原型
typedef void (*nim_vchat_cb_func)(enum NIMVideoChatSessionType type, int64_t channel_id, int code, const char *json_extension, const void *user_data)
NIMVideoChatSessionType::kNIMVideoChatSessionTypeConnect
File:nim_vchat_def.h
参数说明
参数 | 类型 | 说明 |
---|---|---|
type | enum | 回调类型kNIMVideoChatSessionTypeConnect |
channel_id | int64_t | 频道id |
code | int | 错误码NIMVChatConnectErrorCode,200代表连接成功 |
json_extension | char* | Json char* 扩展,如果成功返回 kNIMVChatVideoRecordFile和kNIMVChatRecordFile |
user_data | void* | 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- NIMVChatConnectErrorCode
枚举定义 | 值 | 说明 |
---|---|---|
kNIMVChatConnectDisconn | 0 | 断开连接 |
kNIMVChatConnectStartFail | 1 | 启动失败 |
kNIMVChatConnectTimeout | 101 | 超时 |
kNIMVChatConnectMeetingModeError | 102 | 会议模式错误 |
kNIMVChatConnectRtmpModeError | 103 | 非rtmp用户加入rtmp频道 |
kNIMVChatConnectRtmpNodesError | 104 | 超过频道最多rtmp人数限制 |
kNIMVChatConnectRtmpHostError | 105 | 已经存在一个主播 |
kNIMVChatConnectRtmpCreateError | 106 | 需要旁路直播, 但频道创建者非主播 |
kNIMVChatConnectSuccess | 200 | 成功 |
kNIMVChatConnectLayoutError | 208 | 主播自定义布局错误 |
kNIMVChatConnectInvalidParam | 400 | 错误参数 |
kNIMVChatConnectDesKey | 401 | 密码加密错误 |
kNIMVChatConnectInvalidRequst | 417 | 错误请求 |
kNIMVChatConnectServerUnknown | 500 | 服务器内部错误 |
kNIMVChatConnectLogout | 1001 | 退出 |
kNIMVChatChannelStartFail | 11000 | 发起失败 |
kNIMVChatChannelDisconnected | 11001 | 断开连接 |
kNIMVChatVersionSelfLow | 11002 | 本人SDK版本太低不兼容 |
kNIMVChatVersionRemoteLow | 11003 | 对方SDK版本太低不兼容 |
示例
void nim_vchat_cb(enum NIMVideoChatSessionType type, int64_t channel_id, int code, const char *json_extension, const void *user_data)
{
if (code == 200)
{
switch (type)
{
case kNIMVideoChatSessionTypeStartRes://创建通话结果
break;
case kNIMVideoChatSessionTypeInviteNotify://通话邀请
break;
case kNIMVideoChatSessionTypeCalleeAckRes://确认通话,接受拒绝结果
break;
case kNIMVideoChatSessionTypeCalleeAckNotify://确认通话,接受拒绝通知
break;
case kNIMVideoChatSessionTypeControlRes://NIMVChatControlType 结果
break;
case kNIMVideoChatSessionTypeControlNotify://NIMVChatControlType 通知
break;
case kNIMVideoChatSessionTypeConnect://通话中链接状态通知
break;
case kNIMVideoChatSessionTypePeopleStatus://通话中成员状态
break;
case kNIMVideoChatSessionTypeNetStatus://通话中网络状态
break;
case kNIMVideoChatSessionTypeHangupRes://通话挂断结果
break;
case kNIMVideoChatSessionTypeHangupNotify://通话被挂断通知
break;
case kNIMVideoChatSessionTypeSyncAckNotify://通话接听挂断同步通知
break;
default:
break;
}
}
}