可视门铃

方案概述

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

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

MQTT 连接断开（App 完全退出或进入后台一段时间）时，App 可以通过接入推送，来通知用户来自门铃设备的呼叫。用户点击门铃推送通知后，IPC SDK 对这种情况的呼叫无感知。为了解决该问题，您可以调用 IPC SDK 开放的方法，当用户点击门铃推送的时候，手动把来自推送的门铃呼叫加入到 IPC SDK 的管理范畴。更多信息，参考 处理其他来源的门铃呼叫。

其他方案

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

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

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

获取门铃呼叫管理类

示例代码

Objective-C：

ThingSmartDoorBellManager *manager = [ThingSmartDoorBellManager sharedInstance];

Swift：

let manager = ThingSmartDoorBellManager.sharedInstance()

门铃呼叫模型

门铃呼叫使用 ThingSmartDoorBellCallModel 模型类封装，用来保存门铃呼叫相关信息，以及维护门铃呼叫的当前状态。一次门铃呼叫对应一个 ThingSmartDoorBellCallModel 模型。唯一标识为 messageId，即门铃呼叫的消息 ID。

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

获取门铃呼叫模型

如果您想知道某个门铃呼叫的状态，可通过 ThingSmartDoorBellCallModel 模型返回对应的 ThingSmartDoorBellCallModel 实例来查询。

接口说明

- (ThingSmartDoorBellCallModel *)callModelWithMessageId:(NSString *)messageId;

参数说明

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

注册门铃呼叫监听

监听生效前提是 App 进程处于活跃状态。当 App 进程进入后台，或者被终止后，该监听无效。

接口说明

- (void)addObserver:(id<ThingSmartDoorBellObserver>)observer;

参数说明

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

ThingSmartDoorBellObserver

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

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

示例代码

Objective-C：

@interface CameraDoorbellManager ()<ThingSmartDoorBellObserver>
@property (nonatomic, copy) NSString *messageId;
@end

@implementation CameraDoorbellManager

- (void)doorBellCall:(ThingSmartDoorBellCallModel *)callModel didReceivedFromDevice:(ThingSmartDeviceModel *)deviceModel {
    self.messageId = callModel.messageId;
}

- (void)doorBellCallDidRefuse:(ThingSmartDoorBellCallModel *)callModel {

}

- (void)doorBellCallDidHangUp:(ThingSmartDoorBellCallModel *)callModel {

}

- (void)doorBellCallDidAnsweredByOther:(ThingSmartDoorBellCallModel *)callModel {

}

- (void)doorBellCallDidAnswered:(ThingSmartDoorBellCallModel *)callModel {

}

- (void)doorBellCallDidCanceled:(ThingSmartDoorBellCallModel *)callModel timeOut:(BOOL)isTimeOut {

}

@end

Swift：

class DoorbellManager: NSObject {
    let manager = ThingSmartDoorBellManager.sharedInstance()
    var messageId:String = ""
}

extension DoorbellManager:ThingSmartDoorBellObserver {
    func doorBellCall(_ callModel: ThingSmartDoorBellCallModel!, didReceivedFromDevice deviceModel: ThingSmartDeviceModel!) {
        messageId = callModel.messageId
    }

    func doorBellCallDidRefuse(_ callModel: ThingSmartDoorBellCallModel!) {

    }

    func doorBellCallDidHangUp(_ callModel: ThingSmartDoorBellCallModel!) {

    }

    func doorBellCallDidAnswered(byOther callModel: ThingSmartDoorBellCallModel!) {

    }

    func doorBellCallDidCanceled(_ callModel: ThingSmartDoorBellCallModel!, timeOut isTimeOut: Bool) {

    }
}

移除门铃呼叫监听

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

接口说明

- (void)removeObserver:(id<ThingSmartDoorBellObserver>)observer;

示例代码

Objective-C：

[[ThingSmartDoorBellManager sharedInstance] removeObserver:self];

Swift：

ThingSmartDoorBellManager.sharedInstance()?.remove(self)

忽略指定门铃的后续呼叫

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

属性说明

@property (nonatomic, assign) BOOL ignoreWhenCalling;

属性	说明
ignoreWhenCalling	YES：如果某个设备正在接听一个门铃呼叫时，自动忽略掉此设备的后续呼叫。 NO：不忽略该设备的后续呼叫。 默认值为 YES。

设置所有门铃呼叫超时时间

设置门铃呼叫超时时间后，用户如果在规定时间内未接听门铃呼叫，会回调 doorBellCallDidCanceled 进行通知，并结束此次门铃呼叫。

属性说明

@property (nonatomic, assign) NSInteger doorbellRingTimeOut;

属性	说明
doorbellRingTimeOut	门铃呼叫超时时间，单位为秒，默认值为 25

设置指定门铃呼叫超时时间

根据设备 ID 设置门铃呼叫超时时间后，用户如果在规定时间内未接听门铃呼叫，会回调 doorBellCallDidCanceled 进行通知，并结束此次门铃呼叫。

属性说明

@property (nonatomic, weak) id<ThingSmartDoorBellConfigDataSource> doorBellConfigDataSource;

参数说明

参数	说明
ThingSmartDoorBellConfigDataSource	门铃呼叫设置数据源

ThingSmartDoorBellConfigDataSource

门铃呼叫设置数据源，详见下表：

接口名	参数列表	返回值	描述
doorbellRingTimeOut	NSInteger, NSString *	NSInteger	根据设备 ID，设置门铃呼叫超时时长

接听门铃呼叫

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

接口说明

- (ThingDoorBellError)answerDoorBellCall:(NSString *)messageId;

示例代码

Objective-C：

[[ThingSmartDoorBellManager sharedInstance] answerDoorBellCall:self.messageId];

Swift：

ThingSmartDoorBellManager.sharedInstance()?.answerDoorBellCall(messageId)

拒绝门铃呼叫

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

接口说明

- (void)refuseDoorBellCall:(NSString *)messageId;

示例代码

Objective-C：

[[ThingSmartDoorBellManager sharedInstance] refuseDoorBellCall:self.messageId];

Swift：

ThingSmartDoorBellManager.sharedInstance()?.refuseDoorBellCall(messageId)

挂断门铃呼叫

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

接口说明

- (ThingDoorBellError)hangupDoorBellCall:(NSString *)messageId;

示例代码

Objective-C：

[[ThingSmartDoorBellManager sharedInstance] hangupDoorBellCall:self.messageId];

Swift：

ThingSmartDoorBellManager.sharedInstance()?.hangupDoorBellCall(messageId)

处理其他来源的门铃呼叫

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

接口说明

- (void)generateCall:(NSDictionary *)params;

参数说明

参数	说明
params	收到的呼叫消息数据，推送消息详细解析请参考 Demo

params 键值对说明

key	value
devId	设备 ID
cid	设备 nodeId
edata	消息 ID
eType	收到的呼叫消息类型
time	收到的呼叫消息时间戳

示例代码

更多信息，参考 Demo。

错误码

更多详情，您可以参考 SDK 错误码。

枚举值	错误码	说明
ThingDoorBellError_NoError	0	操作成功，无错误
ThingDoorBellError_CallFailed	-2300	呼叫处理失败，原因可能为： 呼叫事件已结束（已挂断或已拒绝） 同错误码 ThingDoorBellError_NotSupport
ThingDoorBellError_AnsweredByOther	-2301	门铃呼叫时已经被其他用户接听
ThingDoorBellError_DidCanceled	-2302	设备端已经取消了门铃呼叫
ThingDoorBellError_TimeOut	-2303	门铃呼叫已经超时
ThingDoorBellError_AnsweredBySelf	-2304	门铃呼叫已经被接听过
ThingDoorBellError_NotAnswered	-2305	调用挂断呼叫接口，但门铃呼叫还没有被接听
ThingDoorBellError_NotSupport	-2306	不支持此类型设备，例如 doorbell 类型设备

门铃音频资源文件

使用低功耗门铃功能时，您需要下载默认资源文件 resources.zip，解压并加入工程。或者您也可以按默认文件名，添加自定义的音频文件。