public final class CommissioningResult

  1. Object
  2. CommissioningResult

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.

Constructors

public CommissioningResult(String accessoryId, String accessoryName, String structureId, boolean commissionedToThisApp)Creates a result.

Methods

public boolean wasCommissionedToThisApp()Whether this app can address the new accessory.
public String getAccessoryId()The new accessory’s identifier.
public String getAccessoryName()The name the accessory ended up with, which is the user’s choice rather than the one suggested.
public String getStructureId()The home the accessory joined.
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

CommissioningResult

public CommissioningResult(String accessoryId, String accessoryName, String structureId, boolean commissionedToThisApp)
Creates a result. Called by the ports.

Parameters

accessoryId String
the new accessory, or null when the backend did not say
accessoryName String
the name the accessory ended up with, or null
structureId String
the home it joined, or null
commissionedToThisApp boolean
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()
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())