Class RangingSession

java.lang.Object
com.codename1.nearby.ranging.RangingSession
public final class RangingSession extends Object

One ranging conversation with one peer or accessory, obtained from Ranging.prepareSession(RangingRole).

A prepared session has a getLocalToken() to publish and is not yet using the radio. It starts measuring when start(RangingToken) or startAccessory(byte[]) is called and keeps going until stop(), until the platform invalidates it, or until the app exits.

Sessions are not reusable: once stopped or invalidated, prepare another.

  • Method Details

    • getLocalToken

      public RangingToken getLocalToken()

      The token to publish so the peer can range against this device. Never null, and available as soon as the session is prepared.

      Returns

      this device's token for this session

    • getRole

      public RangingRole getRole()

      Which end of the session this device is.

      Returns

      the role this session was prepared with

    • isRunning

      public boolean isRunning()
      true while the radio is measuring. False before start(RangingToken) and after stop(), and false while the session is suspended.

    • start

      public AsyncResource<RangingSession> start(RangingToken peerToken)

      Starts ranging against a peer whose token arrived out of band.

      Parameters
      • peerToken: the peer's token, decoded from the bytes they published
      Returns

      resolves with this session once the radio is measuring, or fails with a NearbyException

    • startAccessory

      public AsyncResource<byte[]> startAccessory(byte[] accessoryConfigurationData)

      Starts ranging against a third-party UWB accessory.

      The accessory publishes a blob of configuration data over its own channel -- in practice a GATT characteristic. Hand those bytes here, and send whatever this resolves with back to the accessory: Apple's Nearby Interaction Accessory Protocol needs that second half of the handshake before the accessory begins ranging.

      Android has no equivalent protocol. There, an accessory simply names the channel and session to join, so build a token with RangingToken.forUwbAddress(byte[], int, int, int, byte[]) and call start(RangingToken) instead; this method fails with NearbyError.NOT_SUPPORTED.

      Parameters
      • accessoryConfigurationData: what the accessory published
      Returns

      resolves with the bytes to send back to the accessory, empty where the platform needs no handshake

    • stop

      public void stop()
      Stops measuring and releases the radio. Idempotent, and safe to call on a session that never started. No further listener callback arrives afterwards.

    • addRangingListener

      public void addRangingListener(RangingListener l)

      Registers a listener. Callbacks arrive on the EDT.

      Parameters
      • l: the listener to add

    • removeRangingListener

      public void removeRangingListener(RangingListener l)

      Removes a listener added by addRangingListener(RangingListener).

      Parameters
      • l: the listener to remove