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

  Modifier and Type
  Method
  Description
  `void`
  `addRangingListener(RangingListener l)`
  Registers a listener.
  `RangingToken`
  `getLocalToken()`
  The token to publish so the peer can range against this device.
  `RangingRole`
  `getRole()`
  Which end of the session this device is.
  `boolean`
  `isRunning()`
  `true` while the radio is measuring.
  `void`
  `removeRangingListener(RangingListener l)`
  Removes a listener added by `addRangingListener(RangingListener)`.
  `AsyncResource<RangingSession>`
  `start(RangingToken peerToken)`
  Starts ranging against a peer whose token arrived out of band.
  `AsyncResource<byte[]>`
  `startAccessory(byte[] accessoryConfigurationData)`
  Starts ranging against a third-party UWB accessory.
  `void`
  `stop()`
  Stops measuring and releases the radio.

  ### Methods inherited from class Object

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

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