点对点音频通话

点对点音频通话功能提供呼叫、接听、挂断、话单通知等功能。阅读该章节,您可以迅速完成一个最简单的点对点音频通话的呼叫接听和挂断功能。

呼叫/接听流程

sequenceDiagram 主叫->>被叫: 主叫发起通话请求(start) 被叫->>被叫: 被叫收到通话请求回调(onReceive) 被叫->>主叫: 被叫响应通话请求(response) 被叫-->>被叫: 呼入的通话已经被该帐号其他端处理回调(onResponsedByOther) 主叫->>主叫: 主叫收到被叫响应回调(onResponse) 主叫->>主叫: 通话建立成功(onCallEstablished) 被叫->>被叫: 通话建立成功(onCallEstablished)

主叫发起通话请求

API介绍

发起一个音频网络通话

API原型

static bool Start(NIMVideoChatMode mode, const std::string& apns_text, const std::string& custom_info, const std::string& json_info)

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
mode enum 音频通话类型,目前只支持音频
apns_text string 推送文本,推送给手机显示
custom_info string 自定义信息,带给接收方
json_extension string Json 扩展,音频通话的扩展参数设置
返回值说明

返回一个bool类型值。若调用成功返回true,否则返回false。一般失败是由于有正在进行的通话导致。

示例
void send_vchat_request(string account)
{
    nim::NIMVideoChatMode mode = kNIMVideoChatModeAudio;
    std::string apns_text = "cocos demo";
    Json::Value value;
    Json::Value uids_value(Json::arrayValue);
    uids_value[0] = account;
    value["uids"] = uids_value;
    value["session_id"] = account;
    value["keepcalling"] = 1;
    value["record"] = 1;
    value["high_rate"] = 1;
    value["audio_call_proximity"] = 1;
    std::string custom_info = "";
    std::string json_info = value.toStyledString();
    nim::VChat::Start(mode, apns_text, custom_info, json_info);
}
特殊说明

在通话发起时,应该设置一个定时器,用于在通话建立前等待超时时能主动结束通话。

被叫收到通话请求回调

API介绍

收到一个点对点音频通话的邀请。由注册通话事件后,在回调中区分。

API原型

typedef std::function SessionStatusCallback;

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeInviteNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension char* Json 扩展,返回kNIMVChatUid发起者,kNIMVChatType对应NIMVideoChatMode, kNIMVChatTime, kNIMVChatCustomInfo
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}

被叫响应通话请求

API介绍

通知邀请方自己的处理结果。如果已有通话存在,需要结束已有通话才能接听新的通话。

API原型

static bool CalleeAck(uint64_t channel_id, bool accept, const std::string& json_extension);

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
channel_id uint64_t 频道id
accept bool 是否接听
json_extension string 扩展的json,接起时有效 参数可选 如{"custom_video":0, "custom_audio":0, "video_quality":0}
返回值说明

返回一个bool类型值。若调用成功返回true,否则返回false(可能channel_id无匹配,如要接起另一路通话前先结束当前通话)

示例
void demo_test_nim_vchat_callee_ack(int64_t channel_id, bool accept, char* session_id)
{
    std::string json_extension = "";
    nim::VChat::CalleeAck(channel_id, accept, json_extension);
}
特殊说明

在通话接听时,应该设置一个定时器,用于在通话建立前等待超时时能主动结束通话。

主叫收到被叫响应回调

API介绍

收到被叫方响应的回调信息通知。由注册通话事件后,在回调中区分。

API原型

typedef std::function SessionStatusCallback;

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeCalleeAckNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension string Json 扩展,返回kNIMVChatUid发起者,kNIMVChatType对应NIMVideoChatMode, kNIMVChatTime, kNIMVChatCustomInfo
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}
特殊说明

呼入的通话已经被该帐号其他端处理回调

API介绍

收到本人在别的端响应的回调通知。由注册通话事件后,在回调中区分。

API原型

typedef std::function SessionStatusCallback;

NIMVideoChatSessionType::kNIMVideoChatSessionTypeSyncAckNotify

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeSyncAckNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension char* Json 扩展,返回kNIMVChatUid发起者,kNIMVChatType对应NIMVideoChatMode, kNIMVChatTime, kNIMVChatCustomInfo
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}
特殊说明

通话建立结果回调

API介绍

通话在对方接听后,双方底层都开始建立连接,以对方加入通话为通话建立成果的标记。

API原型

typedef std::function SessionStatusCallback;

连接状态:

NIMVideoChatSessionType::kNIMVideoChatSessionTypeConnect

对端进出:

NIMVideoChatSessionType::kNIMVideoChatSessionTypePeopleStatus

File:nim_cpp_vchat.h

参数说明

连接状态:

参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeConnect
channel_id int64_t 频道id
code int 错误码NIMVChatConnectErrorCode,200代表连接成功
json_extension char* Json 扩展,如果成功返回 kNIMVChatVideoRecordFile和kNIMVChatRecordFile

对端进出:

参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypePeopleStatus
channel_id int64_t 频道id
code int 状态码,对应NIMVideoChatSessionStatus
json_extension char* Json 扩展,返回kNIMVChatUid,如果是离开带kNIMVChatStatus对应NIMVideoChatUserLeftType
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}
特殊说明

在主叫发起通话和被叫收到邀请后,都应该创建一个定时器,当通话建立超时时,应该按创建失败的流程结束通话。

挂断流程

sequenceDiagram 主叫->>被叫: 结束通话(hangup) 被叫->>被叫: 收到对方结束通话回调(onHangup) 被叫->>被叫: 通话断开(onCallDisconnected) 被叫->>被叫: 话单通知 主叫->>主叫: 通话断开(onCallDisconnected) 主叫->>主叫: 话单通知

结束通话

API介绍

需要在通话结束时调用,用于底层挂断和清理数据,如果是自己主动结束会通知对方。

API原型

static void End(const std::string& json_extension);

File:nim_cpp_vchat.h

参数说明
参数 类型 说明
json_extension char* 拓展参数,无效
返回值说明

无返回值。

示例
nim_vchat_end("");//断开通话
特殊说明

主动结束会返回hangup调用结果的回调通知,对于已经建立连接的通话,结束后返回connect的回调通知,code=1001(kNIMVChatConnectLogout)

收到对方结束通话回调

API介绍

对端主动结束通话,另一端会收到挂断通知。

API原型

typedef std::function SessionStatusCallback;

NIMVideoChatSessionType::kNIMVideoChatSessionTypeHangupNotify

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeHangupNotify
channel_id int64_t 频道id
code int 错误码
json_extension string 无效 Json 扩展
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}

通话断开

API介绍

在通话建立后,会有connect的通知,告知200的成功状态。之后connect返回非200都代表通话断开。

API原型

typedef std::function SessionStatusCallback;

NIMVideoChatSessionType::kNIMVideoChatSessionTypeConnect

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeConnect
channel_id int64_t 频道id
code int 错误码NIMVChatConnectErrorCode,200代表连接成功
json_extension string Json string 扩展,如果成功返回 kNIMVChatVideoRecordFile和kNIMVChatRecordFile
示例
void VChatSessionCb(NIMVideoChatSessionType type, std::uint64_t channel_id, int code, const std::string& json_extension)
{
    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;
        case kNIMVideoChatSessionTypeMp4Notify:            /**< 通知MP4录制状态,包括开始录制和结束录制 */
        break;
        case kNIMVideoChatSessionTypeInfoNotify:        /**< 通知实时音频数据状态 */
        break;
        case kNIMVideoChatSessionTypeVolumeNotify:        /**< 通知实时音频发送和混音的音量状态 */
        break;
        case kNIMVideoChatSessionTypeAuRecordNotify:    /**< 通知音频录制状态,包括开始录制和结束录制 */
        break;
    }
}
特殊说明

大部分因为网络原因导致的通话断开,都会在连接超时后返回connect通知,并且这个超时和IM的账号登陆长链接无关联。