家庭信息管理

本文介绍家庭管理相关的功能，包括创建家庭、修改家庭信息、删除家庭、加入家庭等，获取家庭信息、天气信息，注册监听来接收房间维度的事件回调。

功能说明

家庭管理对应 ThingSmartFamilyBiz 类，实现对家庭的操作。

类名(或协议名)	说明
ThingSmartFamilyBiz	家庭管理类
ThingSmartHomeModel	家庭粗略模型
ThingSmartHome	家庭详细模型
ThingSmartFamilyBizDelegate	家庭代理协议

ThingSmartHomeModel 数据模型

字段	类型	描述
homeId	long long	家庭 ID
name	NSString	家庭名称
geoName	NSString	家庭位置
latitude	double	家庭所在纬度
longitude	double	家庭所在经度

接口列表

创建默认家庭

如果用户账号下没有家庭，可以调用接口创建一个默认家庭，传入家庭名称。家庭创建成功后，通过 success 回调 homeId。
此外，还可以通过注册监听的方式，实现 ThingSmartFamilyBizDelegate 代理方法，接收新建家庭的回调。

接口说明

- (void)createDefaultFamilyWithName:(NSString *)name
                            success:(void(^)(long long homeId))success
                            failure:(ThingFailureError)failure;

参数说明

参数	说明
name	家庭名称
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)createDefaultFamily {
    [[ThingSmartFamilyBiz sharedInstance] createDefaultFamilyWithName:@"" success:^(long long homeId) {

    } failure:^(NSError *error) {

    }];
}

Swift

 func createDefaultFamily() {
    ThingSmartFamilyBiz.sharedInstance().createDefaultFamily(withName: "") { homeId in

    } failure: { error in

    }
}

创建家庭

用户创建一个家庭，包含必要信息，例如家庭名称、家庭房间、家庭定位。家庭创建成功后，通过 success 回调 homeId。
此外，还可以通过注册监听的方式，实现 ThingSmartFamilyBizDelegate 代理方法，接收新增家庭的回调。

接口说明

- (void)addFamilyWithModel:(ThingSmartFamilyRequestModel *)model
                   success:(void(^)(long long homeId))success
                   failure:(ThingFailureError)failure;

参数说明

参数	说明
model	创建家庭请求参数模型
success	成功回调
failure	失败回调

ThingSmartFamilyRequestModel 数据模型

字段	类型	描述
name	NSString	家庭名称
geoName	NSString	家庭所在城市名称
latitude	double	家庭所在纬度
longitude	double	家庭所在经度
rooms	NSArray	家庭下房间名称列表

调用示例

Objective-C

- (void)addFamily {
    ThingSmartFamilyRequestModel *requestModel = [[ThingSmartFamilyRequestModel alloc] init];
    requestModel.geoName = @"";
    requestModel.latitude = 3;
    requestModel.longitude = 45;
    requestModel.name = @"family name";
    requestModel.rooms = @[];
    [[ThingSmartFamilyBiz sharedInstance] addFamilyWithModel:requestModel success:^(long long homeId) {

    } failure:^(NSError *error) {

    }];
}

Swift

func addFamily() {
    let requestModel = ThingSmartFamilyRequestModel()
    requestModel.geoName = ""
    requestModel.latitude = 3
    requestModel.longitude = 45
    requestModel.name = "family name"
    requestModel.rooms = []
    ThingSmartFamilyBiz.sharedInstance().addFamily(with: requestModel) { homeId in

    } failure: { error in

    }
}

删除家庭

家庭所有者删除家庭，当前家庭下所有设备将会重置。
此外，还可以通过注册监听的方式，实现 ThingSmartFamilyBizDelegate 代理方法，接收删除家庭的回调。

接口说明

- (void)deleteFamilyWithHomeId:(long long)homeId
                       success:(ThingSuccessHandler)success
                       failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)removeFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] deleteFamilyWithHomeId:homeId success:^{

    } failure:^(NSError *error) {

    }];
}

Swift

func removeFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().deleteFamily(withHomeId: homeId) {

    } fai
lure: { error in

    }
}

更新家庭信息

更新家庭的位置、名称、经纬度、房间。
此外，还可以通过注册监听的方式，实现 ThingSmartFamilyBizDelegate 代理方法，接收更新家庭的回调。

接口说明

- (void)updateFamilyWithHomeId:(long long)homeId
                         model:(ThingSmartFamilyRequestModel *)model
                       success:(ThingSuccessHandler)success
                       failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
model	更新家庭请求模型
success	成功回调
failure	失败回调

ThingSmartFamilyRequestModel 数据模型

字段	类型	描述
name	NSString	家庭名称
geoName	NSString	家庭所在城市名称
latitude	double	家庭所在纬度
longitude	double	家庭所在经度
rooms	NSArray	家庭下房间名称列表

调用示例

Objective-C

- (void)updateFamily:(long long)homeId {
    ThingSmartFamilyRequestModel *requestModel = [[ThingSmartFamilyRequestModel alloc] init];
    requestModel.geoName = @"";
    requestModel.latitude = 123;
    requestModel.longitude = 30;
    requestModel.name = @"new family name";
    requestModel.rooms = @[];
    [[ThingSmartFamilyBiz sharedInstance] updateFamilyWithHomeId:homeId model:requestModel success:^{

    } failure:^(NSError *error) {

    }];
}

Swift

func updateFamily(homeId:Int64) {
    let requestModel = ThingSmartFamilyRequestModel()
    requestModel.geoName = ""
    requestModel.latitude = 123
    requestModel.longitude = 30
    requestModel.name = "new family name"
    requestModel.rooms = []
    ThingSmartFamilyBiz.sharedInstance().updateFamily(withHomeId: homeId, model: requestModel) {

    } failure: { error in

    }
}

获取家庭粗略信息列表

获取账号下所有的家庭。

接口说明

- (void)getFamilyListWithSuccess:(void(^)(NSArray<ThingSmartHomeModel *> * homes))success
                         failure:(ThingFailureError)failure;

参数说明

参数	说明
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)getFamilyList {
    [[ThingSmartFamilyBiz sharedInstance] getFamilyListWithSuccess:^(NSArray<ThingSmartHomeModel *> *homes) {

    } failure:^(NSError *error) {

    }];
}

Swift

func getFamilyList() {
    ThingSmartFamilyBiz.sharedInstance().getFamilyList { familyList in

    } failure: { error in

    }
}

获取家庭缓存列表

家庭列表本地缓存数据请求完成之后，会自动更新。调用 [ThingSmartFamilyBiz getFamilyListWithSuccess:failure:] 后，缓存列表才有数据。

接口说明

- (NSArray <ThingSmartHomeModel *>*)getCachedHomes;

返回值

缓存的家庭模型。更多信息，请参考 ThingSmartHomeModel 数据模型。

调用示例

Objective-C

[[ThingSmartFamilyBiz sharedInstance] getCachedHomes];

Swift

ThingSmartFamilyBiz.sharedInstance().getCachedHomes()

获取家庭详情

获取家庭详情，包括房间列表、设备列表、群组列表等。

接口说明

- (void)getFamilyDetailWithHomeId:(long long)homeId
                          success:(void(^)(ThingSmartHome *home))success
                          failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)getFamilyDetail:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] getFamilyDetailWithHomeId:homeId success:^(ThingSmartHome *home) {

    } failure:^(NSError *error) {

    }];
}

Swift

func getFamilyDetail(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().getFamilyDetail(withHomeId: homeId) { home in

    } failure: { error in

    }
}

获取家庭所在城市信息

接口说明

- (void)getCityInfo:(double)latitude
          longitude:(double)longitude
            success:(void(^)(ThingSmartFamilyCityModel *cityModel))success
            failure:(ThingFailureError)failure;

参数说明

参数	说明
latitude	家庭所在地区纬度
longitude	家庭所在地区经度
success	成功回调
failure	失败回调

ThingSmartFamilyCityModel 数据模型

字段	类型	描述
area	NSString	家庭所在区域
province	NSString	家庭所在省份
city	NSString	家庭所在城市

调用示例

Objective-C

- (void)getFamilyCity {
    [[ThingSmartFamilyBiz sharedInstance] getCityInfo:12 longitude:12 success:^(ThingSmartFamilyCityModel *cityModel) {

    } failure:^(NSError *error) {

    }];
}

Swift

func getFamilyCity() {
    ThingSmartFamilyBiz.sharedInstance().getCityInfo(12, longitude: 12) { cityInfo in

    } failure: { error in

    }
}

获取家庭所在地区天气粗略信息

返回家庭所在城市的简要天气参数，如城市名称、当天的天气状况（晴、多云、雨等）、天气图片信息。

接口说明

- (void)getHomeWeatherSketchWithHomeId:(long long)homeId
                               success:(void(^)(ThingSmartWeatherSketchModel *))success
                               failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
success	成功回调
failure	失败回调

ThingSmartWeatherSketchModel 数据模型

字段	类型	描述
condition	NSString	天气情况，例如晴、阴、雨等
iconUrl	NSString	天气图标
inIconUrl	NSString	天气图标，高亮
temp	NSString	温度

调用示例

Objective-C

- (void)getWeather:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] getHomeWeatherSketchWithHomeId:homeId success:^(ThingSmartWeatherSketchModel *weather) {

    } failure:^(NSError *error) {

    }];
}

Swift

func getWeather(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().getHomeWeatherSketch(withHomeId: homeId) { weather in

    } failure: { error in

    }
}

获取家庭所在地区天气详细信息

接口说明

- (void)getHomeWeatherDetailWithHomeId:(long long)homeId
                                option:(ThingSmartWeatherOptionModel *)optionModel
                               success:(void(^)(NSArray<ThingSmartWeatherModel *> *))success
                               failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
optionModel	天气详情单位配置模型
success	成功回调
failure	失败回调

ThingSmartWeatherOptionModel 数据模型

字段	类型	描述
pressureUnit	ThingSmartWeatherOptionPressureUnit	气压单位
windspeedUnit	ThingSmartWeatherOptionWindSpeedUnit	风速单位
temperatureUnit	ThingSmartWeatherOptionTemperatureUnit	温度单位
limit	NSInteger	请求的天气详情的个数。若不配置，则默认全部返回

ThingSmartWeatherModel 数据模型

字段	类型	描述
icon	NSString	天气参数图标
name	NSString	天气参数名称
unit	NSString	参数单位
value	NSString	参数值

调用示例

Objective-C

- (void)getWeatherDetail:(long long)homeId {
    ThingSmartWeatherOptionModel *option = [[ThingSmartWeatherOptionModel alloc] init];
    option.pressureUnit = ThingSmartWeatherOptionPressureUnit_hPa;
    [[ThingSmartFamilyBiz sharedInstance] getHomeWeatherDetailWithHomeId:homeId option:option success:^(NSArray<ThingSmartWeatherModel *> *weathers) {

    } failure:^(NSError *error) {

    }];
}

Swift

func getWeatherDetail(homeId:Int64) {
    let option = ThingSmartWeatherOptionModel()
    ThingSmartFamilyBiz.sharedInstance().getHomeWeatherDetail(withHomeId: homeId, option: option) { weathers in

    } failure: { error in

    }
}

离开家庭

将成员从家庭下移除，家庭所有者可以删除管理员及以下角色，管理员仅可以删除普通成员及以下角色。

在 成员信息管理 中，家庭成员角色（ThingHomeRoleType）设置包括：

• owner：家庭所有者
• admin：管理员
• member：普通成员

根据 memberId 角色不同，本接口支持的行为有所不同：

• 如果角色是家庭管理员、普通成员，则为离开家庭。此时该家庭未注销，设备也不会被重置。
• 如果角色是家庭所有者，则为注销家庭。同时，该家庭下所有设备会被重置，效果与删除家庭一致。

接口说明

- (void)leaveFamilyWithHomeId:(long long)homeId
                     memberId:(long long)memberId
                      success:(ThingSuccessHandler)success
                      failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
memberId	从家庭下离开的成员 ID
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)leaveFamily:(long long)homeId memberId:(long long)memberId {
    [[ThingSmartFamilyBiz sharedInstance] leaveFamilyWithHomeId:homeId memberId:memberId success:^{

    } failure:^(NSError *error) {

    }];
}

Swift

func leaveFamily(homeId:Int64, memberId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().leaveFamily(withHomeId: homeId, memberId: memberId) {

    } failure: { error in

    }
}

通过邀请码加入家庭

传入通过 创建家庭成员邀请码 接口生成的邀请码，加入邀请者的家庭。

接口说明

- (void)joinFamilyWithInvitationCode:(NSString *)invitationCode
                             success:(ThingSuccessBOOL)success
                             failure:(ThingFailureError)failure;

参数说明

参数	说明
invitationCode	邀请码
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)joinFamily:(NSString *)invitationCode {
    [[ThingSmartFamilyBiz sharedInstance] joinFamilyWithInvitationCode:invitationCode success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift

func joinFamily(invitationCode:String) {
    ThingSmartFamilyBiz.sharedInstance().joinFamily(withInvitationCode: invitationCode) { result in

    } failure: { error in

    }
}

接受加入家庭的邀请

如果在 添加家庭成员 接口中将 autoAccept 设置为 NO，受邀请者需要同意后才能加入该家庭。此时，在受邀请者账号下调用该接口会接受邀请。

接口说明

- (void)acceptJoinFamilyWithHomeId:(long long)homeId
                           success:(ThingSuccessBOOL)success
                           failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	被邀请加入的家庭 ID
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)acceptFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] acceptJoinFamilyWithHomeId:homeId success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift

func acceptFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().acceptJoinFamily(withHomeId: homeId) { result in

    } failure: { error in

    }
}

拒绝加入家庭的邀请

如果在 添加家庭成员 接口中将 autoAccept 设置为 NO，受邀请者需要同意后才能加入该家庭。此时，在受邀请者账号下调用该接口会拒绝邀请。

接口说明

- (void)rejectJoinFamilyWithHomeId:(long long)homeId
                           success:(ThingSuccessBOOL)success
                           failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	被邀请加入的家庭 ID
success	成功回调
failure	失败回调

调用示例

Objective-C

- (void)rejectFamily:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] rejectJoinFamilyWithHomeId:homeId success:^(BOOL result) {

    } failure:^(NSError *error) {

    }];
}

Swift

func rejectFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().rejectJoinFamily(withHomeId: homeId) { result in

    } failure: { error in

    }
}

对家庭下设备和群组排序

接口说明

- (void)sortDeviceOrGroupWithHomeId:(long long)homeId
                          orderList:(NSArray<ThingSmartFamilyDeviceGroupOrderRequestModel *> *)orderList
                            success:(ThingSuccessHandler)success
                            failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	家庭 ID
orderList	排序列表
success	成功回调
failure	失败回调

ThingSmartFamilyDeviceGroupOrderRequestModel 数据模型

字段	类型	描述
bizId	NSString	设备 ID 或群组 ID
bizType	ThingSmartFamilyParentBizType	枚举值表示 bIzId 类型： ThingSmartFamilyParentBizTypeGroup：群组 ThingSmartFamilyParentBizTypeDevice：设备

调用示例

Objective-C

- (void)sortDeviceList:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] sortDeviceOrGroupWithHomeId:homeId orderList:@[] success:^{

    } failure:^(NSError *error) {

    }];
}

Swift

func sortDeviceList(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().sortDeviceOrGroup(withHomeId: homeId, orderList: []) {

    } failure: { error in

    }
}

获取当前家庭 ID

接口说明

- (long long)getCurrentFamilyId;

返回值

当前所在家庭的 ID。

调用示例

Objective-C

[[ThingSmartFamilyBiz sharedInstance] getCurrentFamilyId];

Swift

ThingSmartFamilyBiz.sharedInstance().getCurrentFamilyId()

获取当前家庭模型

接口说明

- (ThingSmartHomeModel *)getCurrentFamily;

返回值

家庭模型。更多信息，请参考 ThingSmartHomeModel 数据模型。

调用示例

Objective-C

[[ThingSmartFamilyBiz sharedInstance] getCurrentFamily];

Swift

ThingSmartFamilyBiz.sharedInstance().getCurrentFamily()

设置当前家庭 ID

切换当前家庭后，设置家庭 ID，缓存到本地。

接口说明

- (void)setCurrentFamilyId:(long long)homeId;

参数说明

参数	说明
homeId	家庭 ID

调用示例

Objective-C

- (void)setCurrentFamilyId:(long long)homeId {
    [[ThingSmartFamilyBiz sharedInstance] setCurrentFamilyId:homeId];
}

Swift

func setCurrentFamily(homeId:Int64) {
    ThingSmartFamilyBiz.sharedInstance().setCurrentFamilyId(homeId)
}

启动加载当前家庭

当 App 启动完成后，调用该方法加载上次选中的当前家庭，同时设置 appGroupName。如果没有选中任何家庭，则默认家庭列表的第一个家庭为当前家庭。

接口说明

- (void)launchCurrentFamilyWithAppGroupName:(NSString * _Nullable )appGroupName;

参数说明

参数	说明
appGroupName	App 中显示的群组名称

调用示例

Objective-C

[[ThingSmartFamilyBiz sharedInstance] launchCurrentFamilyWithAppGroupName:[ThingCustomConfig sharedInstance].appGroupName];

Swift

ThingSmartFamilyBiz.sharedInstance().launchCurrentFamilyWithAppGroupName（"")

清空当前家庭缓存

接口说明

- (void)clearCurrentFamily;

调用示例

Objective-C

[[ThingSmartFamilyBiz sharedInstance] clearCurrentFamily];

Swift

ThingSmartFamilyBiz.sharedInstance().clearCurrentFamily()

事件回调

ThingSmartFamilyBizDelegate 是家庭管理类的代理协议。您可实现该协议并通过注册监听的方式，接收家庭事件的回调。

注册监听

接口说明

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

参数说明

参数	说明
observer	监听者

调用示例

Objective-C

- (void)addObserver:(id<ThingSmartFamilyBizDelegate>)observer {
    [[ThingSmartRoomBiz sharedInstance] addObserver:observer];
}

Swift

func add(observer:ThingSmartFamilyBizDelegate) {
    ThingSmartRoomBiz.sharedInstance().addObserver(observer)
}

移除监听

接口说明

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

参数说明

参数	说明
observer	监听者

调用示例

Objective-C

- (void)removeObserver:(id<ThingSmartFamilyBizDelegate>)observer {
    [[ThingSmartRoomBiz sharedInstance] removeObserver:observer];
}

Swift

func remove(observer:ThingSmartFamilyBizDelegate) {
    ThingSmartRoomBiz.sharedInstance().removeObserver(observer)
}

家庭代理

ThingSmartFamilyBizDelegate 是家庭管理代理协议，ThingSmartFamilyBiz 通过该协议回调家庭相关的事件，以及家庭下设备新增、删除事件，您可实现该协议来接收事件，从而处理相关逻辑。

接口说明

@protocol ThingSmartFamilyBizDelegate <NSObject>

@optional

/**
* MQTT service connection success callback
*/
- (void)serviceConnectedSuccess;

/**
* The delegate that is instantiated when a home is added.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didAddHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing home is removed.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didRemoveHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of home update information, such as the name.
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model.
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didUpdateHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of switching the current home
*
* @param familyBiz    Instance of family management
* @param homeModel    The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didChangeCurrentHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when a new device is added.
*
* @param familyBiz            Instance of family management
* @param deviceModel       The device model
* @param homeModel            The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz didAddDevice:(ThingSmartDeviceModel *)deviceModel atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing device is removed.
*
* @param familyBiz        Instance of family management
* @param deviceId          Deleted Device ID
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
  didRemoveDevice:(NSString *)deviceId
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when a new group is added.
*
* @param familyBiz         Instance of family management
* @param groupModel       The group model
* @param homeModel         The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
      didAddGroup:(ThingSmartGroupModel *)groupModel
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate that is instantiated when an existing group is removed.
*
* @param familyBiz        Instance of family management
* @param groupId            Deleted group ID
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
   didRemoveGroup:(NSString *)groupId
           atHome:(ThingSmartHomeModel *)homeModel;

/**
* The delegate of updates on the shared device list.
*
* @param familyBiz        Instance of family management
* @param homeModel        The home model
*/
- (void)familyBiz:(ThingSmartFamilyBiz *)familyBiz
   didUpdateSharedListAtHome:(ThingSmartHomeModel *)homeModel;

@end

参数说明

参数	说明
familyBiz	家庭管理类
homeModel	家庭模型