Added in API level 28

RangingResult

class RangingResult : Parcelable
kotlin.Any
   ↳ android.net.wifi.rtt.RangingResult

Ranging result for a request started by WifiRttManager#startRanging(RangingRequest, java.util.concurrent.Executor, RangingResultCallback). Results are returned in RangingResultCallback#onRangingResults(List).

A ranging result is the distance measurement result for a single device specified in the RangingRequest.

Summary

Constants
static Int

Individual range request status, getStatus().

static Int

Individual range request status, getStatus().

static Int

Individual range request status, getStatus().

static Int

The unspecified value.

Inherited constants
Public methods
Int

Boolean
equals(other: Any?)

Int

Int

ByteArray

ByteArray

MacAddress?

Int

The bandwidth used to transmit the RTT measurement frame.

Int

The center frequency of the primary 20 MHz frequency (in MHz) of the channel over which the measurement frames are sent.

Int

Int

PeerHandle?

Long

Int

Int

ResponderLocation?

Int

Boolean

Unit
writeToParcel(dest: Parcel, flags: Int)

Properties
static Parcelable.Creator<RangingResult!>

Constants

STATUS_FAIL

Added in API level 28
static val STATUS_FAIL: Int

Individual range request status, getStatus(). Indicates ranging operation failed and the distance value is invalid.

Value: 1

STATUS_RESPONDER_DOES_NOT_SUPPORT_IEEE80211MC

Added in API level 28
static val STATUS_RESPONDER_DOES_NOT_SUPPORT_IEEE80211MC: Int

Individual range request status, getStatus(). Indicates that the ranging operation failed because the specified peer does not support IEEE 802.11mc RTT operations. Support by an Access Point can be confirmed using android.net.wifi.ScanResult#is80211mcResponder().

On such a failure, the individual result fields of RangingResult such as RangingResult#getDistanceMm() are invalid.

Value: 2

STATUS_SUCCESS

Added in API level 28
static val STATUS_SUCCESS: Int

Individual range request status, getStatus(). Indicates ranging operation was successful and distance value is valid.

Value: 0

UNSPECIFIED

Added in API level 34
static val UNSPECIFIED: Int

The unspecified value.

Value: -1

Public methods

describeContents

Added in API level 28
fun describeContents(): Int
Return
Int a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR

equals

Added in API level 28
fun equals(other: Any?): Boolean
Parameters
obj the reference object with which to compare.
Return
Boolean true if this object is the same as the obj argument; false otherwise.

getDistanceMm

Added in API level 28
fun getDistanceMm(): Int
Return
Int The distance (in mm) to the device specified by getMacAddress() or getPeerHandle().

Note: the measured distance may be negative for very close devices.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

getDistanceStdDevMm

Added in API level 28
fun getDistanceStdDevMm(): Int
Return
Int The standard deviation of the measured distance (in mm) to the device specified by getMacAddress() or getPeerHandle(). The standard deviation is calculated over the measurements executed in a single RTT burst. The number of measurements is returned by getNumSuccessfulMeasurements() - 0 successful measurements indicate that the standard deviation is not valid (a valid standard deviation requires at least 2 data points).

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

getLci

fun getLci(): ByteArray
Return
ByteArray The Location Configuration Information (LCI) as self-reported by the peer. The format is specified in the IEEE 802.11-2016 specifications, section 9.4.2.22.10.

Note: the information is NOT validated - use with caution. Consider validating it with other sources of information before using it. This value cannot be null.

getLcr

fun getLcr(): ByteArray
Return
ByteArray The Location Civic report (LCR) as self-reported by the peer. The format is specified in the IEEE 802.11-2016 specifications, section 9.4.2.22.13.

Note: the information is NOT validated - use with caution. Consider validating it with other sources of information before using it. This value cannot be null.

getMacAddress

Added in API level 28
fun getMacAddress(): MacAddress?
Return
MacAddress? The MAC address of the device whose range measurement was requested. Will correspond to the MAC address of the device in the RangingRequest.

Will return a null for results corresponding to requests issued using a PeerHandle, i.e. using the RangingRequest.Builder#addWifiAwarePeer(PeerHandle) API.

getMeasurementChannelFrequencyMHz

Added in API level 34
fun getMeasurementChannelFrequencyMHz(): Int

The center frequency of the primary 20 MHz frequency (in MHz) of the channel over which the measurement frames are sent.

Return
Int center frequency in Mhz of the channel if available, otherwise UNSPECIFIED is returned.

Exceptions
java.lang.IllegalStateException if getStatus() does not return STATUS_SUCCESS.

getNumAttemptedMeasurements

Added in API level 28
fun getNumAttemptedMeasurements(): Int
Return
Int The number of attempted measurements used in the RTT exchange resulting in this set of results. The number of successful measurements is returned by getNumSuccessfulMeasurements() which at most, if there are no errors, will be 1 less than the number of attempted measurements.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception. If the value is 0, it should be interpreted as no information available, which may occur for one-sided RTT measurements. Instead RangingRequest#getRttBurstSize() should be used instead.

getNumSuccessfulMeasurements

Added in API level 28
fun getNumSuccessfulMeasurements(): Int
Return
Int The number of successful measurements used to calculate the distance and standard deviation. If the number of successful measurements if 1 then then standard deviation, returned by getDistanceStdDevMm(), is not valid (a 0 is returned for the standard deviation).

The total number of measurement attempts is returned by getNumAttemptedMeasurements(). The number of successful measurements will be at most 1 less then the number of attempted measurements.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

getPeerHandle

Added in API level 28
fun getPeerHandle(): PeerHandle?
Return
PeerHandle? The PeerHandle of the device whose reange measurement was requested. Will correspond to the PeerHandle of the devices requested using RangingRequest.Builder#addWifiAwarePeer(PeerHandle).

Will return a null for results corresponding to requests issued using a MAC address.

getRangingTimestampMillis

Added in API level 28
fun getRangingTimestampMillis(): Long
Return
Long The timestamp at which the ranging operation was performed. The timestamp is in milliseconds since boot, including time spent in sleep, corresponding to values provided by android.os.SystemClock#elapsedRealtime().

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

getRssi

Added in API level 28
fun getRssi(): Int
Return
Int The average RSSI, in units of dBm, observed during the RTT measurement.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

getUnverifiedResponderLocation

Added in API level 29
fun getUnverifiedResponderLocation(): ResponderLocation?
Return
ResponderLocation? The unverified responder location represented as ResponderLocation which captures location information the responder is programmed to broadcast. The responder location is referred to as unverified, because we are relying on the device/site administrator to correctly configure its location data.

Will return a null when the location information cannot be parsed.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

hashCode

Added in API level 28
fun hashCode(): Int
Return
Int a hash code value for this object.

is80211mcMeasurement

Added in API level 31
fun is80211mcMeasurement(): Boolean
Return
Boolean The result is true if the IEEE 802.11mc protocol was used (also known as two-sided RTT). If the result is false, a one-side RTT result is provided which does not subtract the turnaround time at the responder.

Only valid if getStatus() returns STATUS_SUCCESS, otherwise will throw an exception.

writeToParcel

Added in API level 28
fun writeToParcel(
    dest: Parcel,
    flags: Int
): Unit
Parameters
dest Parcel: The Parcel in which the object should be written. This value cannot be null.
flags Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Properties

CREATOR

Added in API level 28
static val CREATOR: Parcelable.Creator<RangingResult!>