NERtc Linux SDK  V5.4.10
nertc::IRtcEngineEventHandler类 参考

#include <nertc_engine_event_handler.h>

类 nertc::IRtcEngineEventHandler 继承关系图:
nertc::IRtcEngineEventHandlerEx

Public 成员函数

virtual void onError (int error_code, const char *msg)
 
virtual void onWarning (int warn_code, const char *msg)
 
virtual void onApiCallExecuted (const char *api_name, NERtcErrorCode error, const char *message)
 
virtual void onReleasedHwResources (NERtcErrorCode result)
 
virtual void onJoinChannel (channel_id_t cid, uid_t uid, NERtcErrorCode result, uint64_t elapsed)
 
virtual void onReconnectingStart (channel_id_t cid, uid_t uid)
 
virtual void onConnectionStateChange (NERtcConnectionStateType state, NERtcReasonConnectionChangedType reason)
 
virtual void onRejoinChannel (channel_id_t cid, uid_t uid, NERtcErrorCode result, uint64_t elapsed)
 
virtual void onLeaveChannel (NERtcErrorCode result)
 
virtual void onDisconnect (NERtcErrorCode reason)
 
virtual void onClientRoleChanged (NERtcClientRole oldRole, NERtcClientRole newRole)
 
virtual void onUserJoined (uid_t uid, const char *user_name)
 
virtual void onUserJoined (uid_t uid, const char *user_name, NERtcUserJoinExtraInfo join_extra_info)
 
virtual void onUserLeft (uid_t uid, NERtcSessionLeaveReason reason)
 
virtual void onUserLeft (uid_t uid, NERtcSessionLeaveReason reason, NERtcUserJoinExtraInfo leave_extra_info)
 
virtual void onUserAudioStart (uid_t uid)
 
virtual void onUserAudioStop (uid_t uid)
 
virtual void onUserVideoStart (uid_t uid, NERtcVideoProfileType max_profile)
 
virtual void onUserVideoStop (uid_t uid)
 

详细描述

IRtcEngineEventHandler 回调接口类用于 SDK 向 App 发送回调事件通知,App 通过继承该接口类的方法获取 SDK 的事件通知。 接口类的所有方法都有缺省(空)实现,App 可以根据需要只继承关心的事件。在回调方法中,App 不应该做耗时或者调用可能会引起阻塞的 API(如开启音频或视频等),否则可能影响 SDK 的运行。

成员函数说明

◆ onApiCallExecuted()

virtual void nertc::IRtcEngineEventHandler::onApiCallExecuted ( const char *  api_name,
NERtcErrorCode  error,
const char *  message 
)
inlinevirtual

API调用结束回调。
该回调方法表示 SDK 执行完了一个用户的API调用。

参数
api_nameAPI名称
errorAPI执行结果错误码。
messageAPI执行结果描述。

◆ onClientRoleChanged()

virtual void nertc::IRtcEngineEventHandler::onClientRoleChanged ( NERtcClientRole  oldRole,
NERtcClientRole  newRole 
)
inlinevirtual

直播场景下用户角色已切换回调。
本地用户加入房间后,通过 setClientRole 切换用户角色后会触发此回调。例如主播切换为观众、从观众切换为主播。

注解
直播场景下,如果您在加入房间后调用该方法切换用户角色,调用成功后,会触发以下回调:
  • 主播切观众,本端触发 onClientRoleChanged 回调,远端触发 onUserLeft 回调。
  • 观众切主播,本端触发 onClientRoleChanged 回调,远端触发 onUserJoined 回调。
参数
oldRole切换前的角色。详细信息请参考 NERtcClientRole
newRole切换后的角色。详细信息请参考 NERtcClientRole

◆ onConnectionStateChange()

virtual void nertc::IRtcEngineEventHandler::onConnectionStateChange ( NERtcConnectionStateType  state,
NERtcReasonConnectionChangedType  reason 
)
inlinevirtual

房间连接状态已改变回调。
该回调在房间连接状态发生改变的时候触发,并告知用户当前的房间连接状态和引起房间状态改变的原因。

参数
state当前的房间连接状态。
reason引起当前房间连接状态发生改变的原因。

◆ onDisconnect()

virtual void nertc::IRtcEngineEventHandler::onDisconnect ( NERtcErrorCode  reason)
inlinevirtual

与服务器连接中断,可能原因包括:网络连接失败、服务器关闭该房间、用户被踢出房间等。

注解
  • SDK 在调用 joinChannel 加入房间成功后,如果和服务器失去连接且连续 3 次重连失败,就会触发该回调。
  • 由于非网络原因,客户端可能会和服务器失去连接,此时SDK无需自动重连,直接触发此回调方法。
参数
reason连接中断原因。

◆ onError()

virtual void nertc::IRtcEngineEventHandler::onError ( int  error_code,
const char *  msg 
)
inlinevirtual

发生错误回调。
该回调方法表示 SDK 运行时出现了(网络或媒体相关的)错误。通常情况下,SDK上报的错误意味着SDK无法自动恢复,需要 App 干预或提示用户。

参数
error_code错误码。详细信息请参考 NERtcDMErrorCode
msg错误描述。

◆ onJoinChannel()

virtual void nertc::IRtcEngineEventHandler::onJoinChannel ( channel_id_t  cid,
uid_t  uid,
NERtcErrorCode  result,
uint64_t  elapsed 
)
inlinevirtual

加入房间回调,表示客户端已经登入服务器。

参数
cid客户端加入的房间 ID。
uid用户 ID。如果在 joinChannel 方法中指定了 uid,此处会返回指定的 ID; 如果未指定 uid(joinChannel 时uid=0),此处将返回云信服务器自动分配的 ID。
result返回结果。
elapsed从 joinChannel 开始到发生此事件过去的时间,单位为毫秒。

◆ onLeaveChannel()

virtual void nertc::IRtcEngineEventHandler::onLeaveChannel ( NERtcErrorCode  result)
inlinevirtual

退出房间回调。
App 调用 leaveChannel 方法后,SDK 提示 App 退出房间是否成功。

参数
result返回结果。错误码请参考 NERtcErrorCode 。在快速切换房间时 code 为 kNERtcErrChannelLeaveBySwitchAction。

◆ onReconnectingStart()

virtual void nertc::IRtcEngineEventHandler::onReconnectingStart ( channel_id_t  cid,
uid_t  uid 
)
inlinevirtual

触发重连。
有时候由于网络原因,客户端可能会和服务器失去连接,SDK会进行自动重连,开始自动重连后触发此回调。

参数
cid房间 ID。
uid用户 ID。

◆ onRejoinChannel()

virtual void nertc::IRtcEngineEventHandler::onRejoinChannel ( channel_id_t  cid,
uid_t  uid,
NERtcErrorCode  result,
uint64_t  elapsed 
)
inlinevirtual

重新加入房间回调。
在弱网环境下,若客户端和服务器失去连接,SDK会自动重连。自动重连成功后触发此回调方法。

参数
cid客户端加入的房间 ID。
uid用户 ID。
result返回结果。
elapsed从开始重连到发生此事件过去的时间,单位为毫秒。

◆ onReleasedHwResources()

virtual void nertc::IRtcEngineEventHandler::onReleasedHwResources ( NERtcErrorCode  result)
inlinevirtual

释放硬件资源的回调。
SDK提示释放硬件资源是否成功。

参数
result返回结果。

◆ onUserAudioStart()

virtual void nertc::IRtcEngineEventHandler::onUserAudioStart ( uid_t  uid)
inlinevirtual

远端用户开启音频的回调。

注解
该回调由远端用户调用 enableLocalAudio 方法开启音频采集和发送触发。
参数
uid远端用户ID。

◆ onUserAudioStop()

virtual void nertc::IRtcEngineEventHandler::onUserAudioStop ( uid_t  uid)
inlinevirtual

远端用户停用音频的回调。

注解
该回调由远端用户调用 enableLocalAudio 方法关闭音频采集和发送触发。
参数
uid远端用户ID。

◆ onUserJoined() [1/2]

virtual void nertc::IRtcEngineEventHandler::onUserJoined ( uid_t  uid,
const char *  user_name 
)
inlinevirtual

远端用户(通信场景)/主播(直播场景)加入当前频道回调。

  • 通信场景下,该回调提示有远端用户加入了频道,并返回新加入用户的 ID;如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调
  • 直播场景下,该回调提示有主播加入了频道,并返回该主播的用户 ID。如果在加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。

该回调在如下情况下会被触发:

  • 远端用户调用 joinChannel 方法加入房间。
  • 远端用户网络中断后重新加入房间。
    注解
    直播场景下:
    • 主播间能相互收到新主播加入频道的回调,并能获得该主播的用户 ID。
    • 观众也能收到新主播加入频道的回调,并能获得该主播的用户 ID。
    • 当 Web 端加入直播频道时,只要 Web 端有推流,SDK 会默认该 Web 端为主播,并触发该回调。
    参数
    uid新加入房间的远端用户 ID。
    user_name新加入房间的远端用户名。

◆ onUserJoined() [2/2]

virtual void nertc::IRtcEngineEventHandler::onUserJoined ( uid_t  uid,
const char *  user_name,
NERtcUserJoinExtraInfo  join_extra_info 
)
inlinevirtual

远端用户加入房间事件回调。 远端用户加入房间或断网重连后,SDK 会触发该回调,可以通过返回的用户 ID 订阅对应用户发布的音、视频流。

  • 通信场景下,该回调通知有远端用户加入了房间,并返回新加入用户的 ID;若该用户加入之前,已有其他用户在房间中,该新加入的用户也会收到这些已有用户加入房间的回调。
  • 直播场景下,该回调通知有主播加入了房间,并返回该主播的用户 ID;若该用户加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入房间的回调。
    自从
    V4.6.29
    使用前提
    请在 IRtcEngineEventHandler 接口类中通过 initialize 接口设置回调监听。
    注解

同类型事件发生后,onUserJoined 回调可能会与该回调同时触发,建议您仅注册此回调,不能同时处理两个回调。

  • 当 Web 端用户加入直播场景的房间中,只要该用户发布了媒体流,SDK 会默认该用户为主播,并触发此回调。
    参数说明
    参数名称 类型 描述
    uid uid_t 新加入房间的远端用户 ID。
    join_extra_info NERtcUserJoinExtraInfo 该远端用户加入的额外信息。

◆ onUserLeft() [1/2]

virtual void nertc::IRtcEngineEventHandler::onUserLeft ( uid_t  uid,
NERtcSessionLeaveReason  reason 
)
inlinevirtual

远端用户离开当前房间的回调。
提示有远端用户离开了房间(或掉线)。通常情况下,用户离开房间有两个原因,即正常离开和超时掉线:

  • 正常离开的时候,远端用户会收到正常离开房间的回调提醒,判断用户离开房间。
  • 超时掉线的依据是,在一定时间内(40~50s),用户没有收到对方的任何数据包,则判定为对方掉线。
    参数
    uid离开房间的远端用户 ID。
    reason远端用户离开原因。
  • kNERtcSessionLeaveNormal(0):正常离开。
  • kNERtcSessionLeaveForFailOver(1):用户断线导致离开房间。
  • kNERTCSessionLeaveForUpdate(2):用户因 Failover 导致离开房间,仅 SDK 内部使用。
  • kNERtcSessionLeaveForKick(3):用户被踢导致离开房间。
  • kNERtcSessionLeaveTimeout(4):用户超时退出房间。

◆ onUserLeft() [2/2]

virtual void nertc::IRtcEngineEventHandler::onUserLeft ( uid_t  uid,
NERtcSessionLeaveReason  reason,
NERtcUserJoinExtraInfo  leave_extra_info 
)
inlinevirtual

远端用户离开房间事件回调。

  • 远端用户离开房间或掉线(在 40 ~ 50 秒内本端用户未收到远端用户的任何数据包)后,SDK 会触发该回调。
    自从
    V4.6.29
    使用前提
    请在 IRtcEngineEventHandler 接口类中通过 nertc::IRtcEngine::initialize "initialize" 接口设置回调监听。
    注解
    同类型事件发生后,onUserLeft 回调可能会与该回调同时触发,建议您仅注册此回调,不能同时处理两个回调。
    参数说明
    参数名称 类型 描述
    uid uid_t 离开房间的远端用户 ID。
    reason /ref nertc::NERtcSessionLeaveReason 该远端用户离开的原因,更多请参考 NERtcErrorCode
    • kNERtcSessionLeaveNormal(0):正常离开。
    • kNERtcSessionLeaveForFailOver(1):用户断线导致离开房间。
    • kNERTCSessionLeaveForUpdate(2):用户因 Failover 导致离开房间,仅 SDK 内部使用。
    • kNERtcSessionLeaveForKick(3):用户被踢导致离开房间。
    • kNERtcSessionLeaveTimeout(4):用户超时退出房间。
    leave_extra_info nertc::NERtcUserJoinExtraInfo 该远端用户离开的额外信息。

◆ onUserVideoStart()

virtual void nertc::IRtcEngineEventHandler::onUserVideoStart ( uid_t  uid,
NERtcVideoProfileType  max_profile 
)
inlinevirtual

远端用户开启视频的回调。
启用后,用户可以进行视频通话或直播。

参数
uid远端用户ID。
max_profile视频编码的分辨率,用于衡量编码质量。

◆ onUserVideoStop()

virtual void nertc::IRtcEngineEventHandler::onUserVideoStop ( uid_t  uid)
inlinevirtual

远端用户停用视频的回调。
关闭后,用户只能进行语音通话或者直播。

参数
uid远端用户ID。

◆ onWarning()

virtual void nertc::IRtcEngineEventHandler::onWarning ( int  warn_code,
const char *  msg 
)
inlinevirtual

发生警告回调。
该回调方法表示 SDK 运行时出现了(网络或媒体相关的)警告。通常情况下,SDK 上报的警告信息 App 可以忽略,SDK 会自动恢复。

参数
warn_code警告码。详细信息请参考 NERtcWarnCode
msg警告描述。

该类的文档由以下文件生成: