Added in API level 28

Summary: Ctors | Methods | Inherited Methods

RangingRequest.Builder

---

Kotlin |Java

public static final class RangingRequest.Builder
extends Object

java.lang.Object
↳	android.net.wifi.rtt.RangingRequest.Builder

---

Builder class used to construct RangingRequest objects.

Summary

Public constructors
Builder()

Public methods
RangingRequest.Builder	addAccessPoint(ScanResult apInfo) Add the device specified by the ScanResult to the list of devices with which to measure range.
RangingRequest.Builder	addAccessPoints(List<ScanResult> apInfos) Add the devices specified by the ScanResults to the list of devices with which to measure range.
RangingRequest.Builder	addNon80211mcCapableAccessPoint(ScanResult apInfo) Add the non-802.11mc and non-802.11az capable device specified by the ScanResult to the list of devices with which to measure range.
RangingRequest.Builder	addNon80211mcCapableAccessPoints(List<ScanResult> apInfos) Add the non-802.11mc and non-802.11az capable devices specified by the ScanResult to the list of devices with which to measure range.
RangingRequest.Builder	addResponder(ResponderConfig responder) Add the Responder device specified by the ResponderConfig to the list of devices with which to measure range.
RangingRequest.Builder	addResponders(List<ResponderConfig> responders) Add the devices specified by the ResponderConfigs to the list of devices with which to measure range.
RangingRequest.Builder	addWifiAwarePeer(MacAddress peerMacAddress) Add the device specified by the peerMacAddress to the list of devices with which to measure range.
RangingRequest.Builder	addWifiAwarePeer(PeerHandle peerHandle) Add a device specified by a PeerHandle to the list of devices with which to measure range.
RangingRequest	build() Build RangingRequest given the current configurations made on the builder.
RangingRequest.Builder	setRttBurstSize(int rttBurstSize) Set the RTT Burst size for the ranging request.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(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 wait(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 wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

Added in API level 28

public Builder ()

Public methods

addAccessPoint

Added in API level 28

public RangingRequest.Builder addAccessPoint (ScanResult apInfo)

Add the device specified by the ScanResult to the list of devices with which to measure range. The total number of peers added to a request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Two-sided Ranging will be performed if the local device and the AP support IEEE 802.11az (non-trigger based ranging) or IEEE 802.11mc. AP capability is determined by the method ScanResult#is80211azNtbResponder() or ScanResult#is80211mcResponder(). If both 11az and 11mc are supported by the local device and the AP, 11az non-trigger based ranging will be performed. If two-sided ranging is not supported, one-sided RTT will be performed with no correction for the AP packet turnaround time.

Parameters
apInfo	ScanResult: Information about an Access Point (AP) obtained in a Scan Result. This value cannot be null.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addAccessPoints

Added in API level 28

public RangingRequest.Builder addAccessPoints (List<ScanResult> apInfos)

Add the devices specified by the ScanResults to the list of devices with which to measure range. The total number of peers added to a request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Two-sided Ranging will be performed if the local device and the AP support IEEE 802.11az (non-trigger based ranging) or IEEE 802.11mc. AP capability is determined by the method ScanResult#is80211azNtbResponder() or ScanResult#is80211mcResponder(). If both 11az and 11mc are supported by the local device and the AP, 11az non-trigger based ranging will be performed. If two-sided ranging is not supported, one-sided RTT will be performed with no correction for the AP packet turnaround time.

Parameters
apInfos	List: Information about Access Points (APs) obtained in a Scan Result. This value cannot be null.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addNon80211mcCapableAccessPoint

Added in API level 31

public RangingRequest.Builder addNon80211mcCapableAccessPoint (ScanResult apInfo)

Add the non-802.11mc and non-802.11az capable device specified by the ScanResult to the list of devices with which to measure range. The total number of peers added to a request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Accurate ranging cannot be supported if the Access Point does not support IEEE 802.11mc and IEEE 802.11az, and instead an alternate protocol called one-sided RTT will be used with lower accuracy. Use ScanResult#is80211mcResponder() to verify the Access Point(s) are not 802.11mc capable. Use ScanResult#is80211azNtbResponder() ()} to verify the Access Point)s) are not 802.11az capable.

One-sided RTT does not subtract the RTT turnaround time at the Access Point, which can add hundreds of meters to the estimate. With experimentation, it is possible to use this information to make a statistical estimate of the range by taking multiple measurements to several Access Points and normalizing the result. For some applications this can be used to improve range estimates based on Receive Signal Strength Indication (RSSI), but will not be as accurate as IEEE 802.11mc (two-sided RTT).

Note: one-sided RTT should only be used if you are very familiar with statistical estimation techniques.

Parameters
apInfo	ScanResult: Information about an Access Point (AP) obtained in a Scan Result This value cannot be null.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addNon80211mcCapableAccessPoints

Added in API level 31

public RangingRequest.Builder addNon80211mcCapableAccessPoints (List<ScanResult> apInfos)

Add the non-802.11mc and non-802.11az capable devices specified by the ScanResult to the list of devices with which to measure range. The total number of peers added to a request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Accurate ranging cannot be supported if the Access Point does not support IEEE 802.11mc and IEEE 802.11az, and instead an alternate protocol called one-sided RTT will be used with lower accuracy. Use ScanResult#is80211mcResponder() to verify the Access Point(s) are not 802.11mc capable. Use ScanResult#is80211azNtbResponder() ()} to verify the Access Point(s) are not 802.11az capable.

One-sided RTT does not subtract the RTT turnaround time at the Access Point, which can add hundreds of meters to the estimate. With experimentation, it is possible to use this information to make a statistical estimate of the range by taking multiple measurements to several Access Points and normalizing the result. For some applications this can be used to improve range estimates based on Receive Signal Strength Indication (RSSI), but will not be as accurate as IEEE 802.11mc (two-sided RTT).

Note: one-sided RTT should only be used if you are very familiar with statistical estimation techniques.

Parameters
apInfos	List: Information about Access Points (APs) obtained in a Scan Result. This value cannot be null.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addResponder

Added in API level 33

public RangingRequest.Builder addResponder (ResponderConfig responder)

Add the Responder device specified by the ResponderConfig to the list of devices with which to measure range. The total number of peers added to the request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Two-sided Ranging will be performed if the local device and the AP support IEEE 802.11az (non-trigger based ranging) or IEEE 802.11mc. AP capability is determined by the method ScanResult#is80211azNtbResponder() or ScanResult#is80211mcResponder(). If both 11az and 11mc are supported by the local device and the AP, 11az non-trigger based ranging will be performed. If two-sided ranging is not supported, one-sided RTT will be performed with no correction for the AP packet turnaround time.

Parameters
responder	ResponderConfig: Information on the RTT Responder. This value cannot be null.

Returns
RangingRequest.Builder	The builder, to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addResponders

Added in API level 33

public RangingRequest.Builder addResponders (List<ResponderConfig> responders)

Add the devices specified by the ResponderConfigs to the list of devices with which to measure range. The total number of peers added to a request cannot exceed the limit specified by RangingRequest.getMaxPeers().

Two-sided Ranging will be performed if the local device and the AP support IEEE 802.11az (non-trigger based ranging) or IEEE 802.11mc. AP capability is determined by the method ScanResult#is80211azNtbResponder() or ScanResult#is80211mcResponder(). If both 11az and 11mc are supported by the local device and the AP, 11az non-trigger based ranging will be performed. If two-sided ranging is not supported, one-sided RTT will be performed with no correction for the AP packet turnaround time.

Parameters
responders	List: Information representing the set of access points to be ranged This value cannot be null.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.

addWifiAwarePeer

Added in API level 28

public RangingRequest.Builder addWifiAwarePeer (MacAddress peerMacAddress)

Add the device specified by the peerMacAddress to the list of devices with which to measure range.

The MAC address may be obtained out-of-band from a peer Wi-Fi Aware device. A Wi-Fi Aware device may obtain its MAC address using the IdentityChangedListener provided to WifiAwareManager#attach(AttachCallback, IdentityChangedListener, Handler).

Note: in order to use this API the device must support Wi-Fi Aware android.net.wifi.aware. The peer device which is being ranged to must be configured to publish a service (with any name) with:

Type PublishConfig.PUBLISH_TYPE_UNSOLICITED.

Ranging enabled PublishConfig.Builder.setRangingEnabled(boolean).

Parameters
peerMacAddress	MacAddress: The MAC address of the Wi-Fi Aware peer. This value cannot be null.

Returns
RangingRequest.Builder	The builder, to facilitate chaining builder.setXXX(..).setXXX(..).

addWifiAwarePeer

Added in API level 28

public RangingRequest.Builder addWifiAwarePeer (PeerHandle peerHandle)

Add a device specified by a PeerHandle to the list of devices with which to measure range.

The PeerHandle may be obtained as part of the Wi-Fi Aware discovery process. E.g. using DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], List).

Note: in order to use this API the device must support Wi-Fi Aware android.net.wifi.aware. The requesting device can be either publisher or subscriber in a discovery session. For both requesting device and peer device ranging must be enabled on the discovery session:

PublishConfig.Builder.setRangingEnabled(boolean) for publisher.

Either SubscribeConfig.Builder.setMinDistanceMm(int) or SubscribeConfig.Builder.setMaxDistanceMm(int) must be set to enable ranging on subscriber

Parameters
peerHandle	PeerHandle: The peer handler of the peer Wi-Fi Aware device. This value cannot be null.

Returns
RangingRequest.Builder	The builder, to facilitate chaining builder.setXXX(..).setXXX(..).

build

Added in API level 28

public RangingRequest build ()

Build RangingRequest given the current configurations made on the builder.

Returns
RangingRequest

setRttBurstSize

Added in API level 31

public RangingRequest.Builder setRttBurstSize (int rttBurstSize)

Set the RTT Burst size for the ranging request.

If not set, the default RTT burst size given by RangingRequest.getDefaultRttBurstSize() is used to determine the default value. If set, the value must be in the range RangingRequest.getMinRttBurstSize() and RangingRequest.getMaxRttBurstSize() inclusively, or a IllegalArgumentException will be thrown. Note: RTT burst size is applicable to IEEE 802.11mc, and for one special case it is also applicable to IEEE 802.11az to generate multiple NTB ranging requests per measurement. It is applicable for IEEE 802.11az based ranging requests when MIMO is not available, with the transmit and receive spatial streams between the initiator and responder station is equal to 1. See RangingResult#get80211azNumberOfRxSpatialStreams() and RangingResult#get80211azNumberOfTxSpatialStreams().

Parameters
rttBurstSize	int: The number of FTM packets used to estimate a range.

Returns
RangingRequest.Builder	The builder to facilitate chaining builder.setXXX(..).setXXX(..). This value cannot be null.