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 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