public final class HomeStructure

Object
HomeStructure

One home: HomeKit’s HMHome, a Google Home structure.

A user can have several – a house and a holiday flat – so SmartHome.getStructures() returns a list and isPrimary() marks the one their ecosystem app opens by default. An app that only ever wants one should use the primary rather than the first.

An immutable snapshot; see Accessory for why.

Constructors

public HomeStructure(String id, String name, boolean primary, boolean owner, boolean sceneAuthoringSupported, List<HomeRoom> rooms, List<HomeZone> zones, List<Accessory> accessories, List<Scene> scenes) Creates a structure snapshot.

Methods

`public` `String getId()`	The identifier this structure is addressed by.
`public` `String getName()`	The user-visible name, empty when the structure has none.
`public boolean isPrimary()`	Whether this is the user’s default home.
`public boolean isOwner()`	Whether the user owns this home rather than having been invited to it.
`public boolean isSceneAuthoringSupported()`	Whether scenes can be created and deleted in this home through `SmartHome.createScene(HomeStructure, java.lang.String, java.util.List)` and `SmartHome.deleteScene(Scene)`.
`public` `List<HomeRoom> getRooms()`	The rooms in this home.
`public` `List<HomeZone> getZones()`	The zones in this home.
`public` `List<Accessory> getAccessories()`	Every accessory in this home, in every room and in none.
`public` `List<Scene> getScenes()`	The scenes in this home.
`public` `HomeRoom getRoom(String roomId)`	One room by identifier.
`public` `Accessory getAccessory(String accessoryId)`	One accessory by identifier.
`public` `List<Accessory> getAccessoriesInRoom(String roomId)`	The accessories in one room.
`public` `List<Accessory> getAccessoriesSupporting(Trait trait)`	Every accessory in this home that exposes a trait.
`public` `String toString()`	Returns a string representation of the object.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait, clone

Constructor details

HomeStructure

public HomeStructure(String id, String name, boolean primary, boolean owner, boolean sceneAuthoringSupported, List<HomeRoom> rooms, List<HomeZone> zones, List<Accessory> accessories, List<Scene> scenes)

Creates a structure snapshot. Called by the ports and by the local home; application code receives these rather than building them.

Parameters

id String: the structure identifier
name String: the user-visible name, or null for none
primary boolean: whether this is the user’s default home
owner boolean: whether the user owns this home rather than being a guest
sceneAuthoringSupported boolean: whether scenes can be created and deleted here
rooms List<HomeRoom>: its rooms; null becomes empty
zones List<HomeZone>: its zones; null becomes empty, which is what every backend but HomeKit produces
accessories List<Accessory>: its accessories; null becomes empty
scenes List<Scene>: its scenes; null becomes empty

Throws

IllegalArgumentException: when id is null or empty

Method details

getId

public String getId()

The identifier this structure is addressed by.

Returns

the identifier, never null

getName

public String getName()

The user-visible name, empty when the structure has none. The user’s own text; treat it as untrusted beyond display.

Returns

the name, never null

isPrimary

public boolean isPrimary()

Whether this is the user’s default home.

Always false on iOS. Apple deprecated HMHomeManager.primaryHome in iOS 16.1 as “no longer supported” and shipped nothing to replace it, so the platform genuinely cannot say which home the user thinks of as theirs. The iOS port reports false for every home rather than guessing, and SmartHome.getPrimaryStructure() falls back to the first – which is at least not a claim about what the user prefers.

Returns

true for the primary structure

isOwner

public boolean isOwner()

Whether the user owns this home rather than having been invited to it.

A guest’s permissions vary by home and by accessory, so a write can still fail with HomeError.UNAUTHORIZED in a home they own; this is worth surfacing mainly so an app can explain why a control it offered did not work.

Always false on iOS. HomeKit has no notion of ownership – it reports whether the user is an administrator of the home, which an invited resident can also be – so there is nothing to answer this with. That capability is reported by isSceneAuthoringSupported() instead, which is what it actually governs. Do not use this to decide whether to offer a control; use it only to phrase an explanation after one has failed.

Returns

true when the user is the owner

isSceneAuthoringSupported

public boolean isSceneAuthoringSupported()

Whether scenes can be created and deleted in this home through SmartHome.createScene(HomeStructure, java.lang.String, java.util.List) and SmartHome.deleteScene(Scene).

false on backends that will run a scene but not author one, and for a guest without permission. Check it before offering a “save this as a scene” button.

Returns

true when scenes can be authored here

getRooms

public List<HomeRoom> getRooms()

The rooms in this home.

Returns

an immutable list, possibly empty

getZones

public List<HomeZone> getZones()

The zones in this home.

Empty on every backend but HomeKit, which is the only one with the concept; see HomeZone.

Returns

an immutable list, possibly empty

getAccessories

public List<Accessory> getAccessories()

Every accessory in this home, in every room and in none.

Returns

an immutable list, possibly empty

getScenes

public List<Scene> getScenes()

The scenes in this home.

Returns

an immutable list, possibly empty

getRoom

public HomeRoom getRoom(String roomId)

One room by identifier.

Parameters

roomId String: the identifier to look up, or null

Returns

the room, or null when this home has no such room

getAccessory

public Accessory getAccessory(String accessoryId)

One accessory by identifier.

Parameters

accessoryId String: the identifier to look up, or null

Returns

the accessory, or null when this home has no such accessory

getAccessoriesInRoom

public List<Accessory> getAccessoriesInRoom(String roomId)

The accessories in one room.

Parameters

roomId String: the room to filter by; null selects the accessories that are in no room at all, which is a real state on both backends and easy to lose a device in

Returns

an immutable list, possibly empty

getAccessoriesSupporting

public List<Accessory> getAccessoriesSupporting(Trait trait)

Every accessory in this home that exposes a trait.

Parameters

trait Trait: the trait to look for, or null

Returns

an immutable list, possibly empty

toString

public String toString()

Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())