音视频通话

进入/离开房间

房间创建完成后,客户端需要通过进入/离开房间接口来完成整个音视频会话的生命周期管理。本节介绍 HarmonyOS SDK 中与"进入、离开、请出、掉线与房间结束"相关的典型用法。

1. 进入房间

进入房间前需满足以下条件:

  • 已调用登录接口并登录成功;
  • 已获取到有效的房间号(例如通过 createMeeting 创建,或业务服务器下发)。

进入房间使用接口 enterMeeting:

const meetID = 12345678;  // 要进入的房间号

sdk_engine.enterMeeting(meetID);

进入结果通过回调 enterMeetingRslt 返回:

// 进入房间结果
sdk_engine.on("enterMeetingRslt", (sdkErr) => {
  if (sdkErr === CRVSDK_ERR_DEF.CRVSDKERR_NOERR) {
    // 入会成功,可以打开视频、麦克风、屏幕共享等
  } else {
    // 入会失败,根据错误码提示用户,例如房间不存在、房间已结束等
  }
})

当本端进入房间成功后,房间内其它成员会收到 notifyUserEnterMeeting 通知,可用于更新房间成员列表:

// 有人进入房间通知
sdk_engine.on("notifyUserEnterMeeting", (userID) => {
  // userID 为进入房间的用户 ID
  // 在这里更新 UI(成员列表、参会人数等)
})

相关 API 参考:

2. 主动离开房间

当用户主动退出房间时,调用 exitMeeting 即可:

// 用户点击"离开房间"按钮时调用
sdk_engine.exitMeeting();

接口说明要点:

  • 调用 exitMeeting 不需要等待服务器响应,即使网络较差或已断网,也视为本端已经离会;
  • 离开房间后将不再收到任何房间内的消息;
  • 如果离会时网络正常,房间内其他成员会立刻收到 notifyUserLeftMeeting 通知;
  • 如果离会时网络异常,服务器在内部握手超时后同样会下发 notifyUserLeftMeeting 通知。

房间内其他成员侧可在回调中更新 UI:

// 有人离开房间通知
sdk_engine.on("notifyUserLeftMeeting", (userID) => {
  // 从成员列表中移除 userID,刷新界面
})

若希望彻底结束房间本身(而不仅是某个成员离开),请参考 destroyMeeting。

相关 API 参考:

3. 请出房间

房间内具备相应操作权限的用户(通常是主持人/管理员)可以将其他成员请出房间,使用接口 kickout:

const userID = "user_b";  // 需要被请出的用户 ID
sdk_engine.kickout(userID);

请出结果通过回调 kickoutRslt 返回,仅操作者一方收到:

// 请出成员结果(仅发起请出的一方收到)
sdk_engine.on("kickoutRslt", (userID, sdkErr) => {
  if (sdkErr === CRVSDK_ERR_DEF.CRVSDKERR_NOERR) {
    // 请出成功,可在本端 UI 上做相应提示
  } else {
    // 请出失败,根据错误码提示用户
  }
})

被请出的一方会收到 notifyMeetingDropped 通知,其断开原因为 CRVSDK_DROPPED_KICKOUT(定义见 CRVSDK_MEETING_DROPPED_REASON),可用于做定向提示:

// 与房间断开通知(包括被请出等情况)
sdk_engine.on("notifyMeetingDropped", (reason) => {
  if (reason === CRVSDK_MEETING_DROPPED_REASON.CRVSDK_DROPPED_KICKOUT) {
    // 告知用户:您已被管理员请出房间
  } else {
    // 其它断开原因:网络异常、心跳超时等
  }
})

其余仍在房间中的成员(包括操作者)会收到 notifyUserLeftMeeting 通知,用于刷新成员列表。

相关 API 参考:

4. 掉线离开房间

除主动退会和被请出外,用户也可能因为网络问题等原因被动与服务器断开连接。此时 SDK 会触发 notifyLineOff 回调:

// 断线通知
sdk_engine.on("notifyLineOff", (sdkErr) => {
  // 可根据 sdkErr 显示不同的提示信息
  // 例如:网络异常
})

断开后,本端已不在房间中,且处于未登录状态。
如需恢复会话,需再次调用login,在登录成功后,再调用enterMeeting 进入房间。

相关 API 参考:

5.房间被销毁

当房间被主动销毁(例如管理员调用 destroyMeeting)时,所有仍在房间中的成员都会收到 notifyMeetingStopped 通知:

// 房间被结束通知(所有在会成员都会收到)
sdk_engine.on("notifyMeetingStopped", () => {
  // 典型处理:
  // 1. 关闭本地音视频设备、停止屏幕共享
  // 2. 切换到"会议已结束"界面或返回上一级页面
  // 3. 清理与房间相关的 UI 状态和业务数据
})

收到房间结束通知后,无需再调用 exitMeeting,因为房间已经不存在。如需继续音视频沟通,可由业务端重新创建新房间并再次调用 enterMeeting 进入。

相关 API 参考: