Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/ranging/RangingSession#nestedclasses) \| [Methods](https://developer.android.com/reference/android/ranging/RangingSession#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/ranging/RangingSession#inhmethods)

# RangingSession

*** ** * ** ***


`
public

final

class
RangingSession
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


implements

https://developer.android.com/reference/java/lang/AutoCloseable


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.ranging.RangingSession |

<br />

*** ** * ** ***

Represents a session for performing ranging operations. A `https://developer.android.com/reference/android/ranging/RangingSession` manages
the lifecycle of a ranging operation, including start, stop, and event callbacks.

All methods are asynchronous and rely on the provided `https://developer.android.com/reference/java/util/concurrent/Executor` to invoke
callbacks on appropriate threads.

This class implements `https://developer.android.com/reference/java/lang/AutoCloseable`, ensuring that resources can be
automatically released when the session is closed.

## Summary

| ### Nested classes ||
|---|---|
| ` interface` | `https://developer.android.com/reference/android/ranging/RangingSession.Callback` Callback interface for receiving ranging session events. |

| ### Public methods ||
|---|---|
| ` void` | ` https://developer.android.com/reference/android/ranging/RangingSession#addDeviceToRangingSession(android.ranging.RangingConfig)(https://developer.android.com/reference/android/ranging/RangingConfig deviceRangingParams) ` Adds a new device to an ongoing ranging session. |
| ` void` | ` https://developer.android.com/reference/android/ranging/RangingSession#close()() ` Closes this resource, relinquishing any underlying resources. Requires `https://developer.android.com/reference/android/Manifest.permission#RANGING` |
| ` void` | ` https://developer.android.com/reference/android/ranging/RangingSession#reconfigureRangingInterval(int)(int intervalSkipCount) ` Reconfigures the ranging interval for the current session by setting the interval skip count. |
| ` void` | ` https://developer.android.com/reference/android/ranging/RangingSession#removeDeviceFromRangingSession(android.ranging.RangingDevice)(https://developer.android.com/reference/android/ranging/RangingDevice rangingDevice) ` Removes a specific device from an ongoing ranging session. |
| ` https://developer.android.com/reference/android/os/CancellationSignal` | ` https://developer.android.com/reference/android/ranging/RangingSession#start(android.ranging.RangingPreference)(https://developer.android.com/reference/android/ranging/RangingPreference rangingPreference) ` Starts the ranging session with the provided ranging preferences. |
| ` void` | ` https://developer.android.com/reference/android/ranging/RangingSession#stop()() ` Stops the ranging session. |
| ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/android/ranging/RangingSession#toString()() ` Returns a string representation of the object. |

| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class<?>` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||
| From interface ` https://developer.android.com/reference/java/lang/AutoCloseable ` |---|---| | ` abstract void` | ` https://developer.android.com/reference/java/lang/AutoCloseable#close()() ` Closes this resource, relinquishing any underlying resources. | ||

## Public methods

### addDeviceToRangingSession

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 raw ranging
parameters. Only devices represented by `https://developer.android.com/reference/android/ranging/raw/RawResponderRangingConfig` is supported.
If the provided `https://developer.android.com/reference/android/ranging/RangingConfig` does not match one of these types, the addition fails
and invokes `https://developer.android.com/reference/android/ranging/RangingSession.Callback#onOpenFailed(int)` with a reason of
`https://developer.android.com/reference/android/ranging/RangingSession.Callback#REASON_UNSUPPORTED`.
.   
Requires `https://developer.android.com/reference/android/Manifest.permission#RANGING`

<br />

<br />

##### 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 `https://developer.android.com/reference/android/ranging/raw/RawResponderRangingConfig` This value cannot be `null`. <br /> |

### close

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/Manifest.permission#RANGING`

<br />

### reconfigureRangingInterval

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/Manifest.permission#RANGING`

<br />

| Parameters ||
|---|---|
| `intervalSkipCount` | `int`: the number of intervals to skip, ranging from 0 to 255. Value is between 0 and 255 inclusive <br /> |

### removeDeviceFromRangingSession

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/os/RemoteException` in case of server-side communication
issues.
.   
Requires `https://developer.android.com/reference/android/Manifest.permission#RANGING`

<br />

<br />

##### API Note:

- Currently, this API is supported only for UWB multicast session if using `https://developer.android.com/reference/android/ranging/RangingConfig#RANGING_SESSION_RAW`.

| Parameters ||
|---|---|
| `rangingDevice` | `RangingDevice`: the device to be removed from the session. This value cannot be `null`. <br /> |

### start

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public CancellationSignal start (RangingPreference rangingPreference)
```

Starts the ranging session with the provided ranging preferences.

The `https://developer.android.com/reference/android/ranging/RangingSession.Callback#onOpened()` will be called when the session finishes starting.

The provided `https://developer.android.com/reference/android/ranging/RangingPreference` determines the configuration for the session. A
`https://developer.android.com/reference/android/os/CancellationSignal` is returned to allow the caller to cancel the session if needed.
If the session is canceled, the `https://developer.android.com/reference/android/ranging/RangingSession#close()` method will be invoked automatically to
release resources.

This method conditionally requires one or more permissions depending on the
technologies configured in the `rangingPreference`:

- `https://developer.android.com/reference/android/Manifest.permission#RANGING` is required for UWB, BLE, or RTT ranging sessions.
- `https://developer.android.com/reference/android/Manifest.permission#ACCESS_FINE_LOCATION` is required for Location-based or UWB DL-TDoA ranging sessions.
- `https://developer.android.com/reference/android/Manifest.permission#ACCESS_BACKGROUND_LOCATION` is additionally required if Location-based or UWB DL-TDoA ranging is initiated or continues while the application is in the background.

<br />

<br />

| Parameters ||
|---|---|
| `rangingPreference` | `RangingPreference`: `https://developer.android.com/reference/android/ranging/RangingPreference` the preferences for configuring the ranging session. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/CancellationSignal` | a `https://developer.android.com/reference/android/os/CancellationSignal` to close the session. This value cannot be `null`. <br /> |

### stop

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public void stop ()
```

Stops the ranging session.

This method releases any ongoing ranging operations. If the operation fails,
it will propagate a `https://developer.android.com/reference/android/os/RemoteException` from the system server.


Requires `https://developer.android.com/reference/android/Manifest.permission#RANGING`

<br />

### toString

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public String toString ()
```

Returns a string representation of the object.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/String` | a string representation of the object. <br /> |