# Class HomeStructure

java.lang.Object
com.codename1.home.HomeStructure

public final class HomeStructure extends Object

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.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<Accessory>`
  `getAccessories()`
  Every accessory in this home, in every room and in none.
  `List<Accessory>`
  `getAccessoriesInRoom(String roomId)`
  The accessories in one room.
  `List<Accessory>`
  `getAccessoriesSupporting(Trait trait)`
  Every accessory in this home that exposes a trait.
  `Accessory`
  `getAccessory(String accessoryId)`
  One accessory by identifier.
  `String`
  `getId()`
  The identifier this structure is addressed by.
  `String`
  `getName()`
  The user-visible name, empty when the structure has none.
  `HomeRoom`
  `getRoom(String roomId)`
  One room by identifier.
  `List<HomeRoom>`
  `getRooms()`
  The rooms in this home.
  `List<Scene>`
  `getScenes()`
  The scenes in this home.
  `List<HomeZone>`
  `getZones()`
  The zones in this home.
  `boolean`
  `isOwner()`
  Whether the user owns this home rather than having been invited to it.
  `boolean`
  `isPrimary()`
  Whether this is the user's default home.
  `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)`.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Object

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

- ## 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`: the structure identifier

    - `name`: the user-visible name, or `null` for none

    - `primary`: whether this is the user's default home

    - `owner`: whether the user owns this home rather than being a guest

    - `sceneAuthoringSupported`: whether scenes can be created and deleted here

    - `rooms`: its rooms; `null` becomes empty

    - `zones`: its zones; `null` becomes empty, which is what every backend but HomeKit produces

    - `accessories`: its accessories; `null` becomes empty

    - `scenes`: 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`: 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`: 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`: 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`: the trait to look for, or `null`

    ###### Returns

    an immutable list, possibly empty

  - ### toString

    public String toString()
    Description copied from class: `Object`
    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())
    Overrides:
      `toString` in class `Object`