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

Nested classes

Builder class used to construct RangingResult objects.
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

Gets LTF repetitions that the initiator station (ISTA) used in the preamble of the initiator to responder (I2R) null data PPDU (NDP) for this result.
Int

Gets number of receive spatial streams that the initiator station (ISTA) used for the initiator to responder (I2R) null data PPDU (NDP) for this result.
Int

Gets number of transmit spatial streams that the initiator station (ISTA) used for the initiator to responder (I2R) null data PPDU (NDP) for this result.
Int

Gets LTF repetitions that the responder station (RSTA) used in the preamble of the responder to initiator (I2R) null data PPDU (NDP) for this result.
Int

Int

ByteArray

ByteArray

MacAddress?

Long

Gets maximum time between measurements in microseconds for IEEE 802.
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.
Long

Gets minimum time between measurements in microseconds for IEEE 802.
Int

Int

PeerHandle?

Long

Int

Int

Get Secure HE-LTF protocol version used.
Int

ResponderLocation?

Int

Boolean

Boolean

Boolean

Boolean

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.

get80211azInitiatorTxLtfRepetitionsCount

Added in API level 35
fun get80211azInitiatorTxLtfRepetitionsCount(): Int

Gets LTF repetitions that the initiator station (ISTA) used in the preamble of the initiator to responder (I2R) null data PPDU (NDP) for this result. LTF repetitions is the multiple transmissions of HE-LTF symbols in an HE ranging NDP. An HE-LTF repetition value of 1 indicates no repetitions.

Return
Int LTF repetitions count

get80211azNumberOfRxSpatialStreams

Added in API level 35
fun get80211azNumberOfRxSpatialStreams(): Int

Gets number of receive spatial streams that the initiator station (ISTA) used for the initiator to responder (I2R) null data PPDU (NDP) for this result.

Return
Int Number of spatial streams

get80211azNumberOfTxSpatialStreams

Added in API level 35
fun get80211azNumberOfTxSpatialStreams(): Int

Gets number of transmit spatial streams that the initiator station (ISTA) used for the initiator to responder (I2R) null data PPDU (NDP) for this result.

Return
Int Number of spatial streams

get80211azResponderTxLtfRepetitionsCount

Added in API level 35
fun get80211azResponderTxLtfRepetitionsCount(): Int

Gets LTF repetitions that the responder station (RSTA) used in the preamble of the responder to initiator (I2R) null data PPDU (NDP) for this result. LTF repetitions is the multiple transmissions of HE-LTF symbols in an HE ranging NDP. An HE-LTF repetition value of 1 indicates no repetitions.

Return
Int LTF repetitions count

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

Added in API level 35
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

Added in API level 35
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.

getMaxTimeBetweenNtbMeasurementsMicros

Added in API level 35
fun getMaxTimeBetweenNtbMeasurementsMicros(): Long

Gets maximum time between measurements in microseconds for IEEE 802.11az non-trigger based ranging. The next 11az ranging request needs to be invoked before the maximum time from the last measurement time getRangingTimestampMillis(). Otherwise, the non-trigger based ranging session will be terminated and a new ranging negotiation will happen with the responding station.

getMeasurementBandwidth

Added in API level 34
fun getMeasurementBandwidth(): Int

The bandwidth used to transmit the RTT measurement frame.

Return
Int one of ScanResult.CHANNEL_WIDTH_20MHZ, ScanResult.CHANNEL_WIDTH_40MHZ, ScanResult.CHANNEL_WIDTH_80MHZ, ScanResult.CHANNEL_WIDTH_160MHZ, CHANNEL_WIDTH_80MHZ_PLUS_MHZ or CHANNEL_WIDTH_320MHZ if available, otherwise UNSPECIFIED is returned.

Value is android.net.wifi.ScanResult#CHANNEL_WIDTH_20MHZ, android.net.wifi.ScanResult#CHANNEL_WIDTH_40MHZ, android.net.wifi.ScanResult#CHANNEL_WIDTH_80MHZ, android.net.wifi.ScanResult#CHANNEL_WIDTH_160MHZ, android.net.wifi.ScanResult#CHANNEL_WIDTH_80MHZ_PLUS_MHZ, or android.net.wifi.ScanResult#CHANNEL_WIDTH_320MHZ
Exceptions
java.lang.IllegalStateException if getStatus() does not return STATUS_SUCCESS.

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.

getMinTimeBetweenNtbMeasurementsMicros

Added in API level 35
fun getMinTimeBetweenNtbMeasurementsMicros(): Long

Gets minimum time between measurements in microseconds for IEEE 802.11az non-trigger based ranging. The next 11az ranging measurement request must be invoked after the minimum time from the last measurement time getRangingTimestampMillis() for the peer. Otherwise, cached ranging result will be returned for the peer.

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.

getSecureHeLtfProtocolVersion

Added in API level Baklava
fun getSecureHeLtfProtocolVersion(): Int

Get Secure HE-LTF protocol version used. The secure HE-LTF negotiation supports negotiation of the secure HE-LTF protocol version which allows a responder and an initiator to negotiate the highest mutually supported secure HE-LTF protocol version. Refer IEEE 802.11az-2022 spec, section 9.4.2.298 Ranging Parameters element.

Return
Int Value is between 0 and 7 inclusive

getStatus

Added in API level 28
fun getStatus(): Int
Return
Int The status of ranging measurement: STATUS_SUCCESS in case of success, and STATUS_FAIL in case of failure. Value is android.net.wifi.rtt.RangingResult#STATUS_SUCCESS, android.net.wifi.rtt.RangingResult#STATUS_FAIL, or android.net.wifi.rtt.RangingResult#STATUS_RESPONDER_DOES_NOT_SUPPORT_IEEE80211MC

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.

is80211azNtbMeasurement

Added in API level 35
fun is80211azNtbMeasurement(): Boolean
Return
Boolean The result is true if the IEEE 802.11az non-trigger based protocol was used. If the result is false, and is80211mcMeasurement() is also 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.

is80211mcMeasurement

Added in API level 31
fun is80211mcMeasurement(): Boolean
Return
Boolean The result is true if the IEEE 802.11mc protocol was used. If the result is false, and is80211azNtbMeasurement() is also 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.

isRangingAuthenticated

Added in API level Baklava
fun isRangingAuthenticated(): Boolean
Return
Boolean whether the ranging is authenticated or not. Refer IEEE 802.11az-2022 spec, section 12 Security.

isRangingFrameProtected

Added in API level Baklava
fun isRangingFrameProtected(): Boolean
Return
Boolean whether the ranging frames are protected or not. Refer IEEE 802.11az-2022 spec, section 12 Security.

isSecureHeLtfEnabled

Added in API level Baklava
fun isSecureHeLtfEnabled(): Boolean
Return
Boolean whether the secure HE-LTF is enabled or not. Refer IEEE 802.11az-2022 spec, section 9.4.2.298 Ranging Parameters element.

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