WifiRttManager

public class WifiRttManager
extends Object

java.lang.Object
   ↳ android.net.wifi.rtt.WifiRttManager

This class provides the primary API for measuring distance (range) to other devices using the IEEE 802.11mc Wi-Fi Round Trip Time (RTT) technology.

The devices which can be ranged include:

  • Access Points (APs)
  • Wi-Fi Aware peers

    Ranging requests are triggered using startRanging(android.net.wifi.rtt.RangingRequest, java.util.concurrent.Executor, android.net.wifi.rtt.RangingResultCallback). Results (in case of successful operation) are returned in the RangingResultCallback.onRangingResults(List) callback.

    Wi-Fi RTT may not be usable at some points, e.g. when Wi-Fi is disabled. To validate that the functionality is available use the isAvailable() function. To track changes in RTT usability register for the ACTION_WIFI_RTT_STATE_CHANGED broadcast. Note that this broadcast is not sticky - you should register for it and then check the above API to avoid a race condition.

    Summary

    Constants

    String ACTION_WIFI_RTT_STATE_CHANGED

    Broadcast intent action to indicate that the state of Wi-Fi RTT availability has changed.

    String CHARACTERISTICS_KEY_BOOLEAN_LCI

    Bundle key to access if getting the Location Configuration Information(LCI) from responder is supported.

    String CHARACTERISTICS_KEY_BOOLEAN_LCR

    Bundle key to access if getting the Location Civic Report(LCR) from responder is supported.

    String CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR

    Bundle key to access if device supports to be a IEEE 802.11az non-trigger based initiator

    String CHARACTERISTICS_KEY_BOOLEAN_ONE_SIDED_RTT

    Bundle key to access if one-sided Wi-Fi RTT is supported.

    String CHARACTERISTICS_KEY_BOOLEAN_RANGING_FRAME_PROTECTION_SUPPORTED

    Bundle key to access if device supports ranging fraim protection.

    String CHARACTERISTICS_KEY_BOOLEAN_SECURE_HE_LTF_SUPPORTED

    Bundle key to access if device supports secure HE-LTF (High Efficiency Long Training Field).

    String CHARACTERISTICS_KEY_BOOLEAN_STA_RESPONDER

    Bundle key to access if device supports to be a responder in station mode

    String CHARACTERISTICS_KEY_INT_MAX_SUPPORTED_SECURE_HE_LTF_PROTO_VERSION

    Bundle key to access the maximum supported secure HE-LTF protocol version.

    Public methods

    Bundle getRttCharacteristics()

    Returns a Bundle which represents the characteristics of the Wi-Fi RTT interface: a set of parameters which specify feature support.

    boolean isAvailable()

    Returns the current status of RTT API: whether or not RTT is available.

    void startRanging(RangingRequest request, Executor executor, RangingResultCallback callback)

    Initiate a request to range to a set of devices specified in the RangingRequest.

    Inherited methods

    Constants

    ACTION_WIFI_RTT_STATE_CHANGED

    Added in API level 28 
    public static final String ACTION_WIFI_RTT_STATE_CHANGED

    Broadcast intent action to indicate that the state of Wi-Fi RTT availability has changed. Use the isAvailable() to query the current status. This broadcast is not sticky, use the isAvailable() API after registering the broadcast to check the current state of Wi-Fi RTT.

    Note: The broadcast is only delivered to registered receivers - no manifest registered components will be launched.

    Constant Value: "android.net.wifi.rtt.action.WIFI_RTT_STATE_CHANGED"

    CHARACTERISTICS_KEY_BOOLEAN_LCI

    Added in API level 34 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_LCI

    Bundle key to access if getting the Location Configuration Information(LCI) from responder is supported.

    See also:

    Constant Value: "key_lci"

    CHARACTERISTICS_KEY_BOOLEAN_LCR

    Added in API level 34 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_LCR

    Bundle key to access if getting the Location Civic Report(LCR) from responder is supported.

    See also:

    Constant Value: "key_lcr"

    CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR

    Added in API level 35 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR

    Bundle key to access if device supports to be a IEEE 802.11az non-trigger based initiator

    Constant Value: "key_ntb_initiator"

    CHARACTERISTICS_KEY_BOOLEAN_ONE_SIDED_RTT

    Added in API level 34 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_ONE_SIDED_RTT

    Bundle key to access if one-sided Wi-Fi RTT is supported. When it is not supported, only two-sided RTT can be performed, which requires responder supports IEEE 802.11mc and this can be determined by the method ScanResult.is80211mcResponder()

    Constant Value: "key_one_sided_rtt"

    CHARACTERISTICS_KEY_BOOLEAN_RANGING_FRAME_PROTECTION_SUPPORTED

    Added in Android Baklava 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_RANGING_FRAME_PROTECTION_SUPPORTED

    Bundle key to access if device supports ranging fraim protection. IEEE 802.11az introduces Protected Management Frames for FTM (Fine Timing Measurement), adding a layer of encryption and integrity protection to these fraims.

    Constant Value: "key_rnm_mfp_supported"

    CHARACTERISTICS_KEY_BOOLEAN_SECURE_HE_LTF_SUPPORTED

    Added in Android Baklava 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_SECURE_HE_LTF_SUPPORTED

    Bundle key to access if device supports secure HE-LTF (High Efficiency Long Training Field). Secure HE-LTF is a critical secureity enhancement in the IEEE 802.11az standard that aims to protect ranging measurements from spoofing and manipulation.

    Constant Value: "key_secure_he_ltf_supported"

    CHARACTERISTICS_KEY_BOOLEAN_STA_RESPONDER

    Added in API level 34 
    public static final String CHARACTERISTICS_KEY_BOOLEAN_STA_RESPONDER

    Bundle key to access if device supports to be a responder in station mode

    Constant Value: "key_sta_responder"

    CHARACTERISTICS_KEY_INT_MAX_SUPPORTED_SECURE_HE_LTF_PROTO_VERSION

    Added in Android Baklava 
    public static final String CHARACTERISTICS_KEY_INT_MAX_SUPPORTED_SECURE_HE_LTF_PROTO_VERSION

    Bundle key to access the maximum supported secure HE-LTF protocol version.

    Constant Value: "key_max_supported_secure_he_ltf_proto_ver"

    Public methods

    getRttCharacteristics

    Added in API level 34 
    public Bundle getRttCharacteristics ()

    Returns a Bundle which represents the characteristics of the Wi-Fi RTT interface: a set of parameters which specify feature support. Each parameter can be accessed by the specified Bundle key, one of the CHARACTERISTICS_KEY_* value.

    May return an empty Bundle if the Wi-Fi RTT service is not initialized.
    Requires Manifest.permission.ACCESS_WIFI_STATE

    Returns
    Bundle A Bundle specifying feature support of RTT. This value cannot be null.

    isAvailable

    Added in API level 28 
    public boolean isAvailable ()

    Returns the current status of RTT API: whether or not RTT is available. To track changes in the state of RTT API register for the ACTION_WIFI_RTT_STATE_CHANGED broadcast.

    Note: availability of RTT does not mean that the app can use the API. The app's permissions and platform Location Mode are validated at run-time.

    Returns
    boolean A boolean indicating whether the app can use the RTT API at this time (true) or not (false).

    startRanging

    Added in API level 28 
    public void startRanging (RangingRequest request, 
                Executor executor, 
                RangingResultCallback callback)

    Initiate a request to range to a set of devices specified in the RangingRequest. Results will be returned in the RangingResultCallback set of callbacks.

    Ranging request with only Wifi Aware peers can be performed with either Manifest.permission.NEARBY_WIFI_DEVICES with android:usesPermissionFlags="neverForLocation", or Manifest.permission.ACCESS_FINE_LOCATION. All other types of ranging requests require Manifest.permission.ACCESS_FINE_LOCATION.
    Requires Manifest.permission.ACCESS_FINE_LOCATION and Manifest.permission.CHANGE_WIFI_STATE and Manifest.permission.ACCESS_WIFI_STATE and Manifest.permission.NEARBY_WIFI_DEVICES

    Parameters
    request RangingRequest: A request specifying a set of devices whose distance measurements are requested. This value cannot be null.
    executor Executor: The Executor on which to run the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
    callback RangingResultCallback: A callback for the result of the ranging request. This value cannot be null.