门铃呼叫

方案概述

App 启动状态时，设备成功绑定到家庭且处在在线状态下。App 端通过监听 MQTT 43 协议消息，可收到来自门铃设备的呼叫。之后，App 端可以通过 MQTT 308 协议消息对门铃呼叫进行接听、挂断、拒绝等操作。为了让您更方便地接入门铃业务，降低开发成本，IPC SDK 对这个流程做了完整封装。

当收到门铃呼叫时，IPC SDK 会通过 门铃呼叫监听 通知 App。后续，App 可通过 IPC SDK 对门铃呼叫进行接听、挂断、拒绝等操作。

App 完全退出时，MQTT 连接也随之断开。此时，App 可以通过接入推送来通知用户来自门铃设备的呼叫。用户点击门铃推送通知后，在弹出的门铃呼叫页面，可进行接听、挂断、拒绝等操作。但是，由于此时的门铃呼叫不是通过 MQTT 协议通知 App，所以 IPC SDK 对这种情况的呼叫无感知，同样，使用 IPC SDK 进行接听、挂断、拒绝等操作都会失败。

为了解决这个问题，您可以调用 IPC SDK 开放的方法，在用户点击门铃推送的时候，手动把来自推送的门铃呼叫加入到 IPC SDK 的管理范畴。更多信息，请参考：其他来源门铃呼叫处理。

其他方案

目前，IPC 的可视门铃（type 为 ac_doorbell），完全采用上述方案。但需特别注意，不是所有门铃设备的呼叫原理都跟上述一致。

以 低功耗门铃（type为doorbell）为例，虽然门铃呼叫是通过 MQTT 43 协议消息通知 App，但是接听、挂断、拒绝等操作都是通过 DP 点进行。因此，您可以通过 门铃呼叫监听 来监听来自设备的呼叫。但是对这类设备的接听、挂断、拒绝等操作，需要使用 DP 点相关 API （设备控制）进行单独开发。

对于部分门锁设备，门铃呼叫、接听、挂断、拒绝等操作全是通过 DP 点进行，那么 IPC SDK 对门铃呼叫业务的封装，就完全不适用。

集成推送通知

当应用退出时，MQTT 连接也随之断开。此时，门铃呼叫通知将依赖消息推送。为改善用户体验，您需要另外接入推送 SDK。更多详情，请参考 集成 Push。

当按下门铃时，App 端将会收到推送消息。用户可点击推送消息，进行下一步操作。

门铃呼叫通知

前提条件

App 进程必须处于活跃状态。

查询门铃呼叫管理类

示例代码

 IThingIPCDoorBellManager doorBellInstance = ThingIPCSdk.getDoorbell().getIPCDoorBellManagerInstance();

门铃呼叫模型

门铃呼叫用 ThingDoorBellCallModel 模型类封装，用来保存门铃呼叫相关信息以及维护门铃呼叫的当前状态。

唯一标识为 messageId，即门铃呼叫的消息 ID。一次门铃呼叫对应一个 ThingDoorBellCallModel 模型。

参数	描述
type	门铃呼叫类型：doorbell、ac_doorbell、自定义
devId	设备 ID
messageId	门铃呼叫消息的唯一标识
time	门铃呼叫触发的时间点，Unix 时间戳，单位：秒
answeredBySelf	是否已被自己接听
answeredByOther	是否已被其他人接听
canceled	是否已经被取消

查询门铃呼叫模型

门铃呼叫状态使用 ThingDoorBellCallModel 模型类来维护。如果您想知道某个门铃呼叫的状态，可通过此接口返回对应的 ThingDoorBellCallModel 实例来获取。

接口说明

ThingDoorBellCallModel getCallModelByMessageId(String messageId);

参数说明

参数	说明
messageId	门铃呼叫消息的唯一标识

注册门铃呼叫监听

注册门铃呼叫监听者，传入监听者子类。

前提条件

App 进程处于活跃状态。当 App 进程被清理时，该监听无效。

接口说明

void addObserver(ThingSmartDoorBellObserver observer);

参数说明

参数	说明
observer	门铃呼叫监听者

ThingSmartDoorBellObserver

门铃呼叫监听者，包含门铃呼叫整个生命周期的回调，详见下表：

接口名	参数列表	返回值	描述
doorBellCallDidReceivedFromDevice	ThingDoorBellCallModel，DeviceBean	void	收到设备的门铃呼叫事件
doorBellCallDidHangUp	ThingDoorBellCallModel	void	设备端挂断了门铃呼叫
doorBellCallDidAnsweredByOther	ThingDoorBellCallModel	void	门铃呼叫已经被其他人接听，由业务层去处理是否需要自动取消或者仍然可以接听。 如果不能接听，需要调用 拒绝门铃 方法以结束呼叫。 如果仍然可以接听，在已被其他人接听的情况下，再次接听，只能听见设备的声音，无法开启对讲。
doorBellCallDidCanceled	ThingDoorBellCallModel，boolean	void	门铃呼叫被取消。isTimeOut 参数表明是超时自动取消，还是设备端主动取消
doorBellCallDidAnswered	ThingDoorBellCallModel	void	门铃呼叫已接听
doorBellCallDidRefuse	ThingDoorBellCallModel	void	门铃呼叫已拒绝

示例代码

private ThingDoorBellCallModel mCallModel;

private final ThingSmartDoorBellObserver observer = new ThingSmartDoorBellObserver() {
    @Override
    public void doorBellCallDidReceivedFromDevice(ThingDoorBellCallModel callModel, DeviceBean deviceModel) {
        mCallModel = callModel;
    }

    @Override
    public void doorBellCallDidAnsweredByOther(ThingDoorBellCallModel callModel) {
    }

    @Override
    public void doorBellCallDidCanceled(ThingDoorBellCallModel callModel, boolean isTimeOut) {
    }

    @Override
    public void doorBellCallDidHangUp(ThingDoorBellCallModel callModel) {
    }
};

收到设备的门铃呼叫事件 doorBellCallDidReceivedFromDevice 时，您需要将 ThingDoorBellCallModel 对象或者其中门铃呼叫唯一标识符 messageId 保存起来，作为后续接听、挂断、拒绝等方法的传参。

移除门铃呼叫监听

门铃呼叫监听不使用后，需要在合适的时机移除。

接口说明

void removeObserver(ThingSmartDoorBellObserver observer);

示例代码

移除指定的监听者，调用方法：

if (doorBellInstance != null) {
    doorBellInstance.removeObserver(observer);
}

设置忽略同设备的后续呼叫

正在接听某个设备的门铃呼叫时，设置是否自动忽略掉此设备的后续呼叫。

接口说明

void setIgnoreWhenCalling(boolean ignoreWhenCalling);

参数说明

参数	说明
ignoreWhenCalling	true：如果某个设备正在接听一个门铃呼叫时，自动忽略掉此设备的后续呼叫。 false：不忽略同设备后续呼叫。 默认值为 true。

设置门铃呼叫超时时间

设置门铃呼叫超时时间，在规定时间内门铃呼叫未处理时，会回调 ThingSmartDoorBellObserver#doorBellCallDidCanceled 进行通知，并结束此次门铃呼叫。

接口说明

void setDoorbellRingTimeOut(int doorbellRingTimeOut);

参数说明

参数	说明
doorbellRingTimeOut	门铃呼叫超时时间，默认值为 25，单位：秒

接听门铃

收到门铃呼叫之后，可接听门铃。但是，呼叫可能因为已经被接听、取消或者别的原因而导致无法成功接听。如果接听失败，失败原因会以返回值错误码的形式告知。更多详情，请参考 错误码。

接口说明

int answerDoorBellCall(String messageId);

参数说明

参数	说明
messageId	门铃呼叫消息的唯一标识

示例代码

if (doorBellInstance != null && mCallModel != null) {
    doorBellInstance.answerDoorBellCall(mCallModel.getMessageId());
}

拒绝门铃

收到门铃呼叫之后，可直接拒绝接听门铃。

接口说明

void refuseDoorBellCall(String messageId);

参数说明

参数	说明
messageId	门铃呼叫消息的唯一标识

示例代码

    if (doorBellInstance != null && mCallModel != null) {
        doorBellInstance.refuseDoorBellCall(mCallModel.getMessageId());
    }

挂断门铃

门铃呼叫接听后，可挂断接听。挂断接听可能由于呼叫未被接听等原因为失败，失败原因会以返回值错误码的形式告知。更多详情，请参考 错误码。

接口说明

int hangupDoorBellCall(String messageId);

参数说明

参数	说明
messageId	门铃呼叫消息的唯一标识

示例代码

if (doorBellInstance != null && mCallModel != null) {
    doorBellInstance.hangupDoorBellCall(mCallModel.getMessageId());
}

其他来源门铃呼叫处理

门铃呼叫除了通过 MQTT 协议消息通知客户端，还可能通过推送，所以提供此接口。接口可以根据外部传入参数来生成门铃呼叫模型，达到管理后续门铃接听、挂断、拒绝等操作。

接口说明

void generateCallModel(String deviceId, String messageType, String msgId, long startTime);

参数说明

参数	说明
deviceId	设备 ID
messageType	消息类型
msgId	消息 ID
startTime	门铃呼叫开始时间
cid	子设备 NodeId，可空
示例代码

ThingIPCSdk.getDoorbell().getIPCDoorBellManagerInstance().generateCallModel(deviceId, messageType, msgId, startTime, String cid);

错误码

错误码	说明
0	操作成功，无错误
-2300	呼叫处理失败，原因可能为： 呼叫事件已结束（已挂断或已拒绝） 同错误码 -2306
-2301	调用接听呼叫接口时，如果已经被其他用户接听，返回此错误码
-2302	调用接听呼叫接口时，如果设备端已经取消掉了此次呼叫，返回此错误码
-2303	调用接听呼叫接口时，如果已经超时，返回此错误码
-2304	调用接听呼叫接口时，如果已经接听过，返回此错误码
-2305	调用挂断呼叫接口时，如果门铃呼叫没有被接听，返回此错误码
-2306	不支持此类型设备，比如 doorbell 类型设备