# function onVoipEvent(function listener)

# 功能描述

监听 VoIP 通话相关事件。事件绑定需要在通话开始前完成。

注意：不要在 onLoad、onShow 等生命周期内绑定事件，可能会因为生命周期多次调用而重复绑定。

# 参数

# function listener

事件监听函数

# 回调参数

# Object event

# 返回值

function

取消监听函数，调用后取消监听事件。该函数无参数，无返回值。

# 事件描述

# 1. startVoip

通话开始。

# 2. abortVoip

通话异常中断。

data 参数

status 取值

常见 errMsg

• room status is abort：status=unknown，接收到对端通话异常时触发，需要根据 roomId 关联对端触发的 abortVoip 事件判断真正的异常原因。
• listener waitOtherToJoin timeout：status=abortByListener，接听方加入房间后，拨打方一直未成功加入（可能是网络慢等原因）或异常退出，接听方等待 20s 超时后触发。此时建议分析接听方的情况来排查。
• call interrupted due to close passive float ball：用户将小程序切后台后，会展示小程序浮窗，用户通过浮窗关闭小程序时触发。
• in comming call：小程序通话被其他来电打断时触发。
• call interrupted due to native reason：一般是由于通话过程中一段时间未收到数据包（一般是网络原因），被踢出房间中断通话。

# 3. hangOnVoip

通话被接听（仅接听方触发）。

# 4. cancelVoip

通话未接通，拨打方取消通话。

data 参数

status 取值

# 5. rejectVoip

通话未接通，接听方拒接。

data 参数

status 取值

# 6. hangUpVoip

通话已接通，拨打方/接听方挂断通话。

data 参数

status 取值

origin 取值

为了保持向下兼容，hangUpVoip 事件额外使用 origin 字段提供具体的挂断原因信息。

# 7. endVoip

通话结束。

data 参数

# 8. busy

通话未接通，接听方占线（仅拨打方触发）。

# 9. calling

通话过程中, 双方都会每秒触发一次。

data 参数

# 10. timeout

通话超时未接听。

# 11. joinedRoomByCaller

拨打方加入房间成功（仅拨打方触发）。

# 12. joinFailCaller

拨打方加入房间失败（仅拨打方触发）。

data 参数

# 13. joinFailListener

接听方加入房间失败（仅接听方触发）。

data 参数

# 14. finishVoip

通话完成。返回本次通话结算使用的实际时长。

需从后台获取最终时间后触发，触发时机晚于 endVoip。

data 参数

# 15. callPageOnShow

插件通话页面 onShow。

# 16. showCustomBox

用户点击通话页面自定义按钮，展示自定义组件。

data 参数

# 17. hideCustomBox

用户隐藏自定义组件。

data 参数

# 示例代码

const wmpfVoip = requirePlugin('wmpf-voip').default
const offVoipEvent = wmpfVoip.onVoipEvent(event => {
  console.info(`onVoipEvent`, event)
})

// 需要取消监听时调用
offVoipEvent()