家庭信息管理

更新时间：2024-08-30 03:27:46下载pdf

本文介绍家庭管理相关的功能，包括创建家庭、修改家庭信息、删除家庭等，管理家庭下的设备、群组排序，注册监听来接收家庭维度的事件回调。

功能说明

家庭管理对应 FamilyManagerCoreKit.getFamilyUseCase() 接口，实现对家庭的操作。

家庭信息使用 FamilyBean 来描述，具体属性说明如下：

属性	类型	描述
homeId	Long	家庭 ID
familyName	String	家庭名称
address	String	家庭地理位置名称
lon	Double	经度
lat	Double	纬度
locationCity	String	家庭所在城市位置
familyStatus	Integer	加入家庭邀请的状态： `1`：等待接受（`HomeStatus.WAITING`） `2`：接受（`HomeStatus.ACCEPT`） `3`：拒绝（`HomeStatus.REJECT`）
rooms	List	所有房间列表

TRoomBean 数据属性说明如下：

属性	类型	描述
roomId	long	房间 ID
name	String	房间名称
ids	List	房间下的设备列表

DeviceInRoomBean 数据属性说明如下：

属性	类型	描述
id	String	设备 ID
type	Integer	设备类型 `BizParentTypeEnum`： `5`：群组（`BizParentTypeEnum.GROUP`） `6`：设备（`BizParentTypeEnum.DEVICE`）
name	String	设备名称
roomName	String	设备所在房间名称
iconUrl	String	设备图标
displayOrder	Integer	设备所在房间排序 ID

接口列表

创建默认家庭

提供临时创建一个默认家庭，包含家庭 ID，和家庭名称，家庭无位置信息和房间信息。

接口说明

void createDefaultFamily(String defaultName,
                         IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

参数说明

属性	类型	描述
defaultName	String	家庭名称，最多支持 25 个字符，不能为空
callback	FamilyDataCallback<BizResponseData>	查询结果的回调

调用示例

FamilyManagerCoreKit.getFamilyUseCase().createDefaultFamily("My Home",object :
        IFamilyDataCallback<BizResponseData<FamilyBean>>{
        override fun onSuccess(result: BizResponseData<FamilyBean>?) {
            //successful return result。
            val familybean = result?.data
        }

        override fun onError(errcode: String?, errMsg: String?) {

        }
    })

创建家庭

用户创建一个家庭，包含相关必要信息：家庭名称，家庭房间，家庭地理位置等。

接口说明

void createFamily(CreateFamilyRequestBean requestBean,
       IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

参数说明

参数	类型	说明
requestBean	CreateFamilyRequestBean	创建家庭请求参数模型
callback	IFamilyDataCallback<BizResponseData>	查询结果的回调

CreateFamilyRequestBean 参数说明

参数	类型	说明
familyName	String	家庭名称，最多支持 25 个字符,不能为空
lon	Double	经度，如果不设置家庭位置信息，请设置为 0
lat	Double	纬度，如果不设置家庭位置信息，请设置为 0
address	String	家庭地理位置名称，默认为 Null
rooms	List	房间列表，默认为 Null

调用示例

val family = CreateFamilyRequestBean("My home..."，0d,0d,"",arrayListOf("Living room"," bedroom"))
FamilyManagerCoreKit.getFamilyUseCase().createFamily(family,object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                    val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

加入家庭

通过其他用户分享的家庭邀请码加入到该家庭。

接口说明

void joinFamily(String inviteCode,
                IFamilyDataCallback<Boolean> callback);

参数说明

参数	类型	说明
inviteCode	String	邀请码，不能含有空格，只支持字母和数字
callback	IFamilyDataCallback	查询结果的回调

调用示例

FamilyManagerCoreKit.getFamilyUseCase().joinFamily("HJFGHSH",object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
               //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

查询家庭信息

接口说明

void getFamilyDetail(long homeId,
                     IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

参数说明

参数	类型	说明
homeId	long	家庭 ID
callback	IFamilyDataCallback<BizResponseData>	查询结果的回调

调用示例

//simulate a homeId：7812934L
FamilyManagerCoreKit.getFamilyUseCase().getFamilyDetail(7812934L,object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                            //successful return result。
                         val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

获取当前家庭

获取当前默认家庭，如果没有设置当前默认家庭，则默认获取家庭列表第一个家庭为当前家庭。如果历史操作过设置了当前家庭，则返回上次设置的家庭信息。

设置当前家庭方法，请参考 shiftCurrentFamily。

接口说明

void getCurrentDefaultFamilyDetail(IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

参数说明

参数	类型	说明
callback	IFamilyDataCallback<BizResponseData>	查询结果的回调如果家庭下有缓存，并且账号下存在该家庭，则返回缓存的数据模型。如果没有缓存，则默认获取家庭列表的第一个家庭的数据。接口报错会返回本地磁盘缓存数据。只有当本地没有缓存，并且接口报错，才会回调 `onError()`。

调用示例

FamilyManagerCoreKit.getFamilyUseCase().getCurrentDefaultFamilyDetail(object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                  //successful return result。
                val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

设置当前家庭

设置当前家庭，记录磁盘缓存，下次启动可以直接获取该家庭信息。

接口说明

void shiftCurrentFamily(long homeId,IFamilyDataCallback<Boolean> callback);

参数说明

参数	类型	说明
homeId	long	当前家庭 ID
callback	IFamilyDataCallback	查询结果的回调

调用示例

//仅用于设置缓存当前家庭 ID，其中如果是非法家庭 ID，则会报错。
FamilyManagerCoreKit.getFamilyUseCase().shiftCurrentFamily(homeId, object :IFamilyDataCallback<Boolean>{
            override fun onSuccess(success: Boolean?) {
                //success:Is the setting successful?
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

查询家庭缓存信息

接口说明

FamilyBean getDefaultFamilyBean(long homeId);

参数说明

参数	类型	说明
homeId	long	家庭 ID
return	FamilyBean	查询结果

调用示例

val cacheFamilyBean = FamilyManagerCoreKit.getFamilyUseCase().getDefaultFamilyBean(homeId)

查询家庭天气

查询家庭所在城市的简要天气参数。包括天气状况（晴、多云、雨等）和天气图片信息。

接口说明

void getHomeWeather(double lon, double lat,
                     IFamilyDataCallback<WeatherBean> callback);

参数说明

参数	类型	说明
lon	Double	经度
lat	Double	纬度
callback	IFamilyDataCallback	查询结果的回调

调用示例

FamilyManagerCoreKit.getFamilyUseCase().getHomeWeather(120.0,120.0,object:IFamilyDataCallback<WeatherBean>{
            override fun onSuccess(city: WeatherBean?) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

查询家庭所在城市

接口说明

void getCityByLatLon(double lon, double lat,
                      IFamilyDataCallback<LocationCityBean\> listener);

参数说明

参数	类型	说明
lon	Double	经度
lat	Double	纬度
callback	IFamilyDataCallback	查询结果的回调

调用示例

FamilyManagerCoreKit.getFamilyUseCase().getCityByLatLon(120.0,120.0,object:IFamilyDataCallback<LocationCityBean>{
            override fun onSuccess(city: LocationCityBean?) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

查询家庭列表

查询当前账号下的全部家庭。

接口说明

void getFamilyList(IFamilyDataCallback<BizResponseData<List<FamilyBean>>> callback);

参数说明

参数	类型	说明
callback	IFamilyDataCallback<BizResponseData<List>>	查询结果的回调

调用示例

  FamilyManagerCoreKit.getFamilyUseCase().getFamilyList(object :
            IFamilyDataCallback<BizResponseData<List<FamilyBean>>>{
            override fun onSuccess(result: BizResponseData<List<FamilyBean>>?) {
                val familyList = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

完善和更新家庭信息

创建家庭以后，想要完善家庭信息或修改家庭的信息，例如家庭名称，家庭地理位置，可以调用此方法。

接口说明

void updateFamily(long homeId, CreateFamilyRequestBean requestBean,
                  IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

参数说明

参数	类型	说明
homeId	long	家庭 ID
family	CreateFamilyRequestBean	创建家庭请求参数模型
callback	IFamilyDataCallback<BizResponseData>	查询结果的回调

调用示例

val family = CreateFamilyRequestBean("my home", 0d, 0d, "",arrayListOf("room1", "room2"))
FamilyManagerCoreKit.getFamilyUseCase().updateFamily(homeId, family, object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                   //successful return result。
                    val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

家庭维度下设备和群组排序

家庭下的设备和群组排序。

接口说明

void sortDeviceAndGroupInHome(String homeId, List<DeviceAndGroupInHomeBean> list,
                              IFamilyDataCallback<Boolean> callback);

参数说明

参数	类型	说明
homeId	long	家庭 ID
devList	List	按照列表排序的设备和群组
callback	IFamilyDataCallback	查询结果的回调

DeviceAndGroupInHomeBean 的数据模型属性说明：

参数	类型	说明
bizId	String	设备或者群组 ID
bizType	Integer	设备类型 `BizParentTypeEnum`： `5`：群组（`BizParentTypeEnum.GROUP`） `6`：设备（`BizParentTypeEnum.DEVICE`）

调用示例

val devList = arrayListOf<DeviceAndGroupInHomeBean>()
        devList.add(DeviceAndGroupInHomeBean().apply {
            bizId = "xxxxxxxxx01"
            bizType = BizParentTypeEnum.GROUP.type
        })
        devList.add(DeviceAndGroupInHomeBean().apply {
            bizId = "xxxxxxxxx02"
            bizType = BizParentTypeEnum.DEVICE.type
        })
//The default sorting for the settings is according to the devList order.

FamilyManagerCoreKit.getFamilyUseCase().sortDeviceAndGroupInHome(homeId,devList,object :
            IFamilyDataCallback<Boolean>{
            override fun onSuccess(result: Boolean) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

删除家庭

如果家庭下没有其他成员，则可以通过家庭拥有者账号删除家庭。
如果家庭下有其他成员，则家庭拥有者账号不能删除家庭。

接口说明

void dismissFamily(long homeId, IFamilyDataCallback<Boolean> callback);

参数说明

参数	类型	说明
homeId	long	家庭 ID
callback	IFamilyDataCallback	查询结果的回调

调用示例

   FamilyManagerCoreKit.getFamilyUseCase().dismissFamily(homeId,object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
               //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

离开家庭

家庭拥有者和普通成员可离开家庭。家庭拥有者也可以先转移权限之后才能离开家庭。

接口说明

void leaveFamily(long homeId, long memberId,
                  IFamilyDataCallback<Boolean> callback);

参数说明

参数	类型	说明
homeId	long	家庭 ID
memberId	long	家庭成员 ID，获取方式请参考家庭成员管理
callback	IFamilyDataCallback	查询结果的回调

调用示例

FamilyManagerCoreKit.getFamilyUseCase().leaveFamily(homeId,memberId,object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
                 //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

隐藏设备

这部分接口在 HomeSDK，通过 PluginManager.service(IThingHomePlugin::class.java).newHomeInstance(homeId) 获取接口方法。隐藏设备所用到的 DeviceAndGroupInHomeBean 所有属性如下：

属性	类型	描述
bizId	String	家庭 ID
bizType	int	类型设备：`BizParentTypeEnum.DEVICE` 群组：`BizParentTypeEnum.GROUP`

获取隐藏设备列表

获取家庭下的全部隐藏设备列表。

接口说明

 void queryHidedDeviceGroupList(IThingResultCallback<ArrayList<DeviceAndGroupInHomeBean>> callback);

参数说明

参数	类型	说明
callback	IResponse<ArrayList>	结果的回调

调用示例

 val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).queryHidedDeviceGroupList(object: IThingResultCallback<java.util.ArrayList<DeviceAndGroupInHomeBean>>{
        override fun onSuccess(result: java.util.ArrayList<DeviceAndGroupInHomeBean>?) { 
        }

        override fun onError(errorCode: String?, errorMessage: String?) {
           
        }
    })

隐藏设备列表

隐藏设备列表。

接口说明

 void hideDeviceGroup(List<DeviceAndGroupInHomeBean> devIds, IThingResultCallback<Boolean> callback);

参数说明

参数	类型	说明
devIds	List	需要隐藏的设备列表
callback	IResponse	结果的回调

调用示例

 val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).hideDeviceGroup(listof("devid1","devid2"))(object: IThingResultCallback<Boolean>{
        override fun onSuccess(result: Boolean) { 
        }

        override fun onError(errorCode: String?, errorMessage: String?) {
           
        }
    })

取消隐藏设备列表

取消隐藏设备列表。

接口说明

  void showDeviceGroup(List<DeviceAndGroupInHomeBean> devIds, IThingResultCallback<Boolean> callback);

参数说明

参数	类型	说明
devIds	List	需要取消隐藏的设备列表
callback	IResponse	结果的回调

调用示例

val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).showDeviceGroup(listof("devid1"))(object: IThingResultCallback<Boolean>{
        override fun onSuccess(result: Boolean) { 
        }

        override fun onError(errorCode: String?, errorMessage: String?) {
           
        }
    })

事件回调

家庭新增删除信息变更监听

接口说明

家庭下如果有新增家庭，删除家庭，收到家庭邀请，家庭信息变更，家庭切换，家庭下分享设备变更（删除或者增加），家庭下分享群组变更（删除或者增加），云端 MQTT 服务成功等消息，可以通过注册 FamilyChangeListener 接口回调收到通知。

public interface FamilyChangeListener {
/**
     * Family added successfully.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which added.
     */
    void onFamilyAdded(long homeId);

    /**
     * Family invitation.
     *
     * @param homeId   The ID of the family which you are invited to.
     * @param homeName The name of the family which you are invited to.
     */
    void onFamilyInvite(long homeId, String homeName);

    /**
     * Family deleted successfully.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which removed.
     * @param isBySelfRemoved is removed family by self
     */
    void onFamilyRemoved(long homeId, boolean isBySelfRemoved);

    /**
     * Family information changed.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which information that changed.
     */
    void onFamilyInfoChanged(long homeId);

    /**
     * Current family ID, family name. If familyId is NONE_FAMILY_ID, it means there is no family and you need to jump to the page to create a family.
     *
     * @param familyId
     * @param familyName
     */
    void onFamilyShift(long familyId, String familyName);

    /**
     * Shared device list changes.
     * Used for multi-device data synchronization.
     * @param sharedDeviceList The list of shared devices.
     */
    void onSharedDeviceList(List<DeviceBean> sharedDeviceList);

    /**
     * Shared group list changes.
     * Used for multi-group data synchronization.
     * @param sharedGroupList The list of groups shared.
     */
    void onSharedGroupList(List<GroupBean> sharedGroupList);

    /**
     * The mobile phone successfully connects to the Thing Cloud server and receives this notification.
     * Local data and server data may be inconsistent or the device cannot be controlled,
     * You can call the getHomeDetail interface under Home to reinitialize the data.
     */
    void onServerConnectSuccess();
}

调用示例

val listener = object :FamilyChangeListener{
            override fun onFamilyAdded(homeId: Long) {

            }

            override fun onFamilyInvite(homeId: Long, homeName: String?) {

            }

            override fun onFamilyRemoved(homeId: Long, isBySelfRemoved: Boolean) {

            }

            override fun onFamilyInfoChanged(homeId: Long) {

            }

            override fun onFamilyShift(familyId: Long, familyName: String?) {

            }

            override fun onSharedDeviceList(sharedDeviceList: MutableList<DeviceBean>?) {

            }

            override fun onSharedGroupList(sharedGroupList: MutableList<GroupBean>?) {

            }

            override fun onServerConnectSuccess() {

            }
        }
//Register FamilyChange listener
FamilyManagerCoreKit.registerFamilyChangeListener(listener)

//Unregister FamilyChange listener
FamilyManagerCoreKit.unregisterFamilyChangeListener(listener)

家庭设备新增删除状态监听

接口说明

家庭下如果有新增设备，新增群组，设备移除，群组解散，Mesh 设备添加，则可以通过注册 IThingHomeStatusListener 接口回调收到通知。

public interface IThingHomeStatusListener {

    /**
     * Device add successfully.
     *
     * @param devId The ID of the device which added.
     */
    void onDeviceAdded(String devId);

    /**
     * Device deleted successfully.
     *
     * @param devId The ID of the device which removed.
     */
    void onDeviceRemoved(String devId);

    /**
     * Group add successfully.
     *
     * @param groupId The ID of the group which added.
     */
    void onGroupAdded(long groupId);

    /**
     * Group deleted successfully.
     *
     * @param groupId The ID of the group which removed.
     */
    void onGroupRemoved(long groupId);

    /**
     * Blue mesh add successfully.
     *
     * @param meshId The ID of the mesh which added.
     */
    void onMeshAdded(String meshId);
}

调用示例

val listener = object :IThingHomeStatusListener{
            override fun onDeviceAdded(devId: String?) {

            }

            override fun onDeviceRemoved(devId: String?) {

            }

            override fun onGroupAdded(groupId: Long) {

            }

            override fun onGroupRemoved(groupId: Long) {

            }

            override fun onMeshAdded(meshId: String?) {

            }
        }
//Register HomeStatus listener
FamilyManagerCoreKit.registerHomeStatusListener(0,listener)
//unregister HomeStatus listener
FamilyManagerCoreKit.unregisterHomeStatusListener(0,listener)

上一篇家庭管理

下一篇家庭成员管理