门铃呼叫

更新时间:2023-09-19 03:00:53下载pdf

门铃设备成功绑定到家庭,且保持在线状态时,如果有人按门铃,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 门铃呼叫已拒绝

    收到设备的门铃呼叫事件 didReceivedFromDevice 时,建议保存 ThingSmartDoorBellCallModel 对象,或者其中门铃呼叫唯一标识符 messageId 起来,作为后续接听、挂断、拒绝等方法的请求参数。

    示例代码

    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

    接听门铃呼叫

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

    接口说明

    - (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 收到的呼叫消息数据

    params 键值对说明

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

    错误码

    更多详情,您可以参考 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,解压并加入工程。或者您也可以按默认文件名,添加自定义的音频文件。