点对点音视频通话

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

呼叫/接听流程

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

主叫发起通话请求

API介绍

发起一个音视频网络通话

API原型

NIM_SDK_DLL_API bool nim_vchat_start(enum NIMVideoChatMode mode, const char *apns_text, const char *custom_info, const char *json_extension, const void *user_data)

File:nim_vchat.h

参数说明
参数 类型 说明
mode enum 音视频通话类型,音频或音视频
apns_text char* 推送文本,推送给手机显示
custom_info char* 自定义信息,带给接收方
json_extension char* Json 扩展,音视频通话的扩展参数设置
user_data void* 无效扩展
返回值说明

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

示例
void send_vchat_request(bool audio,char* account)
{
    enum NIMVideoChatMode mode = kNIMVideoChatModeAudio;
    char* apns_text = "语音通话邀请";
    char* custom_info = "test";
    json_value* value_root = json_object_new(0);
    json_value* value_uids = json_array_new(0);

    uint32_t length = 0;
    char* buf = NULL;

    json_object_push(value_root, "need_badge", json_integer_new(0));
    json_object_push(value_root, "need_nick", json_integer_new(0));
    json_object_push(value_root, "record", json_integer_new(0));
    json_object_push(value_root, "session_id", json_string_new(account));
    json_object_push(value_root, "sound", json_integer_new(0));
    json_array_push(value_uids, json_string_new(account));
    json_object_push(value_root, "uids", value_uids);
    json_object_push(value_root, "video_quality", json_integer_new(5));
    json_object_push(value_root, "video_record", json_integer_new(0));
    json_object_push(value_root, kNIMVChatMaxVideoRate, json_integer_new(200000));

    length = json_measure(value_root);
    buf = (char*)calloc(1, length);
    json_serialize(buf, value_root);

    /*目前只有音频通话*/
    if (!audio)
    {
        mode = kNIMVideoChatModeVideo;
        apns_text = "视频通话邀请";
    }

    nim_vchat_start(mode, apns_text, custom_info, buf, NULL);
    json_value_free(value_root);
    free(buf);
}
特殊说明

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

被叫收到通话请求回调

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)

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeInviteNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension char* Json 扩展,返回kNIMVChatUid发起者,kNIMVChatType对应NIMVideoChatMode, kNIMVChatTime, kNIMVChatCustomInfo
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原型

NIM_SDK_DLL_API bool nim_vchat_callee_ack(int64 channel_id, bool accept, const char *json_extension, const void *user_data)

File:nim_vchat.h

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

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

示例
void demo_test_nim_vchat_callee_ack(int64_t channel_id, bool accept, char* session_id)
{
    json_value* value = json_object_new(0);
    uint32_t lenght = 0;
    char* buf = NULL;
    json_object_push(value, "record", json_integer_new(0));
    json_object_push(value, "session_id", json_string_new(session_id));
    json_object_push(value, "video_quality", json_integer_new(0));
    json_object_push(value, "video_record", json_integer_new(0));
    lenght = json_measure(value);
    buf = (char*)calloc(1, lenght);
    json_serialize(buf, value);
    nim_vchat_callee_ack(channel_id_, accept, buf, NULL);
    json_value_free(value);
    free(buf);
}
特殊说明

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

主叫收到被叫响应回调

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)

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeCalleeAckNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension char* Json 扩展,返回kNIMVChatUid被邀请者,kNIMVChatType对应NIMVideoChatMode, kNIMVChatAccept
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::kNIMVideoChatSessionTypeSyncAckNotify

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeSyncAckNotify
channel_id int64_t 频道id
code int 无效错误码
json_extension char* Json 扩展,返回 kNIMVChatTime,kNIMVChatType对应NIMVideoChatMode,kNIMVChatAccept,kNIMVChatClient
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

对端进出:

NIMVideoChatSessionType::kNIMVideoChatSessionTypePeopleStatus

File:nim_vchat_def.h

参数说明

连接状态:

参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeConnect
channel_id int64_t 频道id
code int 错误码NIMVChatConnectErrorCode,200代表连接成功
json_extension char* Json 扩展,如果成功返回 kNIMVChatVideoRecordFile和kNIMVChatRecordFile
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

对端进出:

参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypePeopleStatus
channel_id int64_t 频道id
code int 状态码,对应NIMVideoChatSessionStatus
json_extension char* Json 扩展,返回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;
        }
    }
}
特殊说明

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

挂断流程

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

结束通话

API介绍

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

API原型

void nim_vchat_end(const char *json_extension)

File:nim_vchat.h

参数说明
参数 类型 说明
json_extension char* Json 扩展,kNIMVChatSessionId
返回值说明

无返回值。

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

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

收到对方结束通话回调

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::kNIMVideoChatSessionTypeHangupNotify

File:nim_vchat_def.h

参数说明
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeHangupNotify
channel_id int64_t 频道id
code int 错误码
json_extension char* 无效 Json 扩展
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介绍

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

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,不做任何处理
示例
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;
        }
    }
}
特殊说明

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

话单通知

API介绍

在一通通话结束后,会返回一个通话话单,以IM自定义系统消息的形式发出。

API原型

在线消息广播通知:

NIM_SDK_DLL_API void nim_talk_reg_receive_cb (const char *json_extension, nim_talk_receive_cb_func cb, const void *user_data)

离线、同步消息广播通知:

NIM_SDK_DLL_API void nim_talk_reg_receive_msgs_cb (const char *json_extension, nim_talk_receive_cb_func cb, const void *user_data)

File:nim_talk.h

参数说明
参数 类型 说明
json_extension char* json 扩展
cb function 音视频通话回调接口
user_data void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
示例
void nim_msg_receive_callback(const char* msg,const char* json_extension,const void* user_data)
{
        printf("callback receive msg! msg is %s\n",msg);
}
nim_talk_reg_receive_cb("",nim_msg_receive_callback,"");
特殊说明

通过IM消息中的系统通知,得到对应的attach,话单详情可以参考C代码示例中的attach解析。