RangingSession

public final class RangingSession
extends Object implements AutoCloseable

java.lang.Object
   ↳ android.ranging.RangingSession

Represents a session for performing ranging operations. A RangingSession manages the lifecycle of a ranging operation, including start, stop, and event callbacks.

All methods are asynchronous and rely on the provided Executor to invoke callbacks on appropriate threads.

This class implements AutoCloseable, ensuring that resources can be automatically released when the session is closed.

Summary

Nested classes

interface RangingSession.Callback

Callback interface for receiving ranging session events. 

Public methods

void addDeviceToRangingSession(RangingConfig deviceRangingParams)

Adds a new device to an ongoing ranging session.

void close()

Closes this resource, relinquishing any underlying resources. Requires android.Manifest.permission.RANGING

void reconfigureRangingInterval(int intervalSkipCount)

Reconfigures the ranging interval for the current session by setting the interval skip count.

void removeDeviceFromRangingSession(RangingDevice rangingDevice)

Removes a specific device from an ongoing ranging session.

CancellationSignal start(RangingPreference rangingPreference)

Starts the ranging session with the provided ranging preferences.

void stop()

Stops the ranging session.

String toString()

Returns a string representation of the object.

Inherited methods

Public methods

addDeviceToRangingSession

public void addDeviceToRangingSession (RangingConfig deviceRangingParams)

Adds a new device to an ongoing ranging session.

This method allows for adding a new device to an active ranging session using either raw or out-of-band (OOB) ranging parameters. Only devices represented by RawResponderRangingConfig or OobResponderRangingConfig are supported. If the provided RangingConfig does not match one of these types, the addition fails and invokes Callback.onOpenFailed(int) with a reason of Callback.REASON_UNSUPPORTED.


Requires android.Manifest.permission.RANGING

API Note:
  • If the underlying ranging technology cannot support this dynamic addition, failure will be indicated via Callback#onStartFailed(REASON_UNSUPPORTED, RangingDevice)
Parameters
deviceRangingParams RangingConfig: the ranging parameters for the device to be added, which must be an instance of either RawResponderRangingConfig or OobResponderRangingConfig. This value cannot be null.

close

public void close ()

Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement. Requires android.Manifest.permission.RANGING

reconfigureRangingInterval

public void reconfigureRangingInterval (int intervalSkipCount)

Reconfigures the ranging interval for the current session by setting the interval skip count. The intervalSkipCount defines how many intervals should be skipped between successive ranging rounds. Valid values range from 0 to 255.
Requires android.Manifest.permission.RANGING

Parameters
intervalSkipCount int: the number of intervals to skip, ranging from 0 to 255. Value is between 0 and 255 inclusive

removeDeviceFromRangingSession

public void removeDeviceFromRangingSession (RangingDevice rangingDevice)

Removes a specific device from an ongoing ranging session.

This method removes a specified device from the active ranging session, stopping further ranging operations for that device. The operation is handled by the system server and may throw a RemoteException in case of server-side communication issues.


Requires android.Manifest.permission.RANGING

API Note:
Parameters
rangingDevice RangingDevice: the device to be removed from the session. This value cannot be null.

start

public CancellationSignal start (RangingPreference rangingPreference)

Starts the ranging session with the provided ranging preferences.

The Callback.onOpened() will be called when the session finishes starting.

The provided RangingPreference determines the configuration for the session. A CancellationSignal is returned to allow the caller to cancel the session if needed. If the session is canceled, the close() method will be invoked automatically to release resources.
Requires android.Manifest.permission.RANGING

Parameters
rangingPreference RangingPreference: RangingPreference the preferences for configuring the ranging session. This value cannot be null.
Returns
CancellationSignal a CancellationSignal to close the session. This value cannot be null.

stop

public void stop ()

Stops the ranging session.

This method releases any ongoing ranging operations. If the operation fails, it will propagate a RemoteException from the system server.
Requires android.Manifest.permission.RANGING

toString

public String toString ()

Returns a string representation of the object.

Returns
String a string representation of the object.