Class CommissioningResult

java.lang.Object
com.codename1.home.commissioning.CommissioningResult
public final class CommissioningResult extends Object

What came of a commissioning attempt.

Success does not mean you got a device

This is the type that has to carry the least comfortable fact in the whole API. Commissioning adds an accessory to the user's ecosystem, and whether your app can then see or control it is a separate question with a different answer per backend:

  • iOS, MatterSupport -- the accessory joins the user's HomeKit home and appears in your graph on the next refresh, where you can control it like any other. This result carries no id: Apple's sheet reports that the flow finished and does not say what was added or which home it went to, and the user is free to pick a different home than the one you asked for. Call com.codename1.home.SmartHome#refresh() and look at what is new. wasCommissionedToThisApp() is false unless the build asked for a fabric of its own -- see CommissioningRequest.setCommissionToThisApp(boolean) -- in which case a successful flow means the accessory joined it, because the extension's commissioning step failing is what would have failed the flow.
  • Android, Google Home APIs -- the accessory joins the user's Google Home and, if the user granted your app access to that structure, appears in your graph. You get an id and it works.
  • Android, Play services commissioning alone -- the accessory joins the user's Google Home and your app is told nothing more. There is no id, and there is no graph to look it up in; see com.codename1.home.HomeAvailability#COMMISSIONING_ONLY.

wasCommissionedToThisApp() is that distinction, made explicit so it cannot be missed. An app that assumes it got a device shows a "your new device" screen with nothing on it -- and on two of these three backends that is what it would get.

  • Constructor Details

    • CommissioningResult

      public CommissioningResult(String accessoryId, String accessoryName, String structureId, boolean commissionedToThisApp)

      Creates a result. Called by the ports.

      Parameters

      • accessoryId: the new accessory, or null when the backend did not say

      • accessoryName: the name the accessory ended up with, or null

      • structureId: the home it joined, or null

      • commissionedToThisApp: whether this app can address the accessory

  • Method Details

    • wasCommissionedToThisApp

      public boolean wasCommissionedToThisApp()

      Whether this app can address the new accessory.

      When false, the accessory was added to the user's home successfully and there is nothing more you can do with it from here -- tell the user it worked and send them to their ecosystem app, rather than showing an empty device screen. See the class note.

      Returns

      true when getAccessoryId() is usable

    • getAccessoryId

      public String getAccessoryId()

      The new accessory's identifier.

      Returns

      the identifier, or null when wasCommissionedToThisApp() is false

    • getAccessoryName

      public String getAccessoryName()

      The name the accessory ended up with, which is the user's choice rather than the one suggested.

      Returns

      the name, never null; empty when the backend did not say

    • getStructureId

      public String getStructureId()

      The home the accessory joined.

      The user can pick a different home than the one requested, so this is worth reading rather than assuming.

      Returns

      the structure identifier, or null when the backend did not say

    • 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