WifiAwareManager

Kotlin |Java

open class WifiAwareManager

kotlin.Any
↳	android.net.wifi.aware.WifiAwareManager

This class provides the primary API for managing Wi-Fi Aware operations: discovery and peer-to-peer data connections.

The class provides access to:

Initialize a Aware cluster (peer-to-peer synchronization). Refer to attach(android.net.wifi.aware.AttachCallback,android.os.Handler).
Create discovery sessions (publish or subscribe sessions). Refer to WifiAwareSession.publish(PublishConfig, DiscoverySessionCallback, Handler) and WifiAwareSession.subscribe(SubscribeConfig, DiscoverySessionCallback, Handler).
Create a Aware network specifier to be used with ConnectivityManager.requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) to set-up a Aware connection with a peer. Refer to WifiAwareNetworkSpecifier.Builder.

Aware may not be usable when Wi-Fi is disabled (and other conditions). To validate that the functionality is available use the isAvailable() function. To track changes in Aware usability register for the ACTION_WIFI_AWARE_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.

An application must use attach(android.net.wifi.aware.AttachCallback,android.os.Handler) to initialize a Aware cluster - before making any other Aware operation. Aware cluster membership is a device-wide operation - the API guarantees that the device is in a cluster or joins a Aware cluster (or starts one if none can be found). Information about attach success (or failure) are returned in callbacks of AttachCallback. Proceed with Aware discovery or connection setup only after receiving confirmation that Aware attach succeeded - AttachCallback.onAttached(WifiAwareSession). When an application is finished using Aware it must use the WifiAwareSession.close() API to indicate to the Aware service that the device may detach from the Aware cluster. The device will actually disable Aware once the last application detaches.

Once a Aware attach is confirmed use the WifiAwareSession.publish(PublishConfig, DiscoverySessionCallback, Handler) or WifiAwareSession.subscribe(SubscribeConfig, DiscoverySessionCallback, to create publish or subscribe Aware discovery sessions. Events are called on the provided callback object DiscoverySessionCallback. Specifically, the DiscoverySessionCallback.onPublishStarted(PublishDiscoverySession) and DiscoverySessionCallback.onSubscribeStarted( return PublishDiscoverySession and SubscribeDiscoverySession objects respectively on which additional session operations can be performed, e.g. updating the session PublishDiscoverySession.updatePublish(PublishConfig) and SubscribeDiscoverySession.updateSubscribe(SubscribeConfig). Sessions can also be used to send messages using the DiscoverySession.sendMessage(PeerHandle, int, byte[]) APIs. When an application is finished with a discovery session it must terminate it using the DiscoverySession.close() API.

Creating connections between Aware devices is managed by the standard ConnectivityManager.requestNetwork(NetworkRequest,. The NetworkRequest object should be constructed with:

Summary

Constants
static String	`ACTION_WIFI_AWARE_RESOURCE_CHANGED` Intent broadcast sent whenever Wi-Fi Aware resource availability has changed.
static String	`ACTION_WIFI_AWARE_STATE_CHANGED` Broadcast intent action to indicate that the state of Wi-Fi Aware availability has changed and all active Aware sessions are no longer usable.
static String	`EXTRA_AWARE_RESOURCES` Sent as a part of `ACTION_WIFI_AWARE_RESOURCE_CHANGED` that contains an instance of `AwareResources` representing the current Wi-Fi Aware resources.
static Int	`WIFI_AWARE_DATA_PATH_ROLE_INITIATOR` Connection creation role is that of INITIATOR.
static Int	`WIFI_AWARE_DATA_PATH_ROLE_RESPONDER` Connection creation role is that of RESPONDER.
static Int	`WIFI_AWARE_DISCOVERY_LOST_REASON_PEER_NOT_VISIBLE` Reason code provided in `DiscoverySessionCallback.onServiceLost(PeerHandle, int)` indicating that the service advertised by the peer is no longer visible.
static Int	`WIFI_AWARE_DISCOVERY_LOST_REASON_UNKNOWN` Reason code provided in `DiscoverySessionCallback.onServiceLost(PeerHandle, int)` indicating that the service was lost for unknown reason.

Public methods
open Unit	`attach(attachCallback: AttachCallback, identityChangedListener: IdentityChangedListener, handler: Handler?)` Attach to the Wi-Fi Aware service - enabling the application to create discovery sessions or create connections to peers.
open Unit	`attach(attachCallback: AttachCallback, handler: Handler?)` Attach to the Wi-Fi Aware service - enabling the application to create discovery sessions or create connections to peers.
open AwareResources?	`getAvailableAwareResources()` Return the available resources of the Wi-Fi aware service: a set of parameters which specify limitations on service usage, e.
open Characteristics?	`getCharacteristics()` Returns the characteristics of the Wi-Fi Aware interface: a set of parameters which specify limitations on configurations, e.
open Unit	`getPairedDevices(executor: Executor, resultsCallback: Consumer<MutableList<String!>!>)` Get all the paired devices configured by the calling app.
open Boolean	`isAvailable()` Returns the current status of Aware API: whether or not Aware is available.
open Boolean	`isDeviceAttached()` Return the current status of the Aware service: whether or not the device is already attached to an Aware cluster.
open Boolean	`isInstantCommunicationModeEnabled()` Return the current status of the Wifi Aware instant communication mode.
open Unit	`isOpportunisticModeEnabled(executor: Executor, resultsCallback: Consumer<Boolean!>)` Indicate whether all Wi-Fi Aware sessions created by the calling app are opportunistic as defined and configured by `setOpportunisticModeEnabled(boolean)` Requires `android.Manifest.permission#ACCESS_WIFI_STATE`
open Boolean	`isSetChannelOnDataPathSupported()` Return the device support for setting a channel requirement in a data-path request.
open Unit	`removePairedDevice(alias: String)` Remove the target paired device setup by the caller by `DiscoverySession.initiatePairingRequest(PeerHandle, String, int, String)` and `DiscoverySession.acceptPairingRequest(int, PeerHandle, String, int, String)` Requires `android.Manifest.permission#CHANGE_WIFI_STATE`
open Unit	`resetPairedDevices()` Reset all paired devices setup by the caller by `DiscoverySession.initiatePairingRequest(PeerHandle, String, int, String)` and `DiscoverySession.acceptPairingRequest(int, PeerHandle, String, int, String)` Requires `android.Manifest.permission#CHANGE_WIFI_STATE`
open Unit	`setOpportunisticModeEnabled(enabled: Boolean)` Set all Wi-Fi Aware sessions created by the calling app to be opportunistic.

Constants

ACTION_WIFI_AWARE_RESOURCE_CHANGED

Added in API level 33

static val ACTION_WIFI_AWARE_RESOURCE_CHANGED: String

Intent broadcast sent whenever Wi-Fi Aware resource availability has changed. The resources are attached with the EXTRA_AWARE_RESOURCES extra. The resources can also be obtained using the getAvailableAwareResources() method. To receive this broadcast, apps must hold android.Manifest.permission#ACCESS_WIFI_STATE.

Note: The broadcast is only delivered to registered receivers - no manifest registered components will be launched.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Value: "android.net.wifi.aware.action.WIFI_AWARE_RESOURCE_CHANGED"

ACTION_WIFI_AWARE_STATE_CHANGED

Added in API level 26

static val ACTION_WIFI_AWARE_STATE_CHANGED: String

Broadcast intent action to indicate that the state of Wi-Fi Aware availability has changed and all active Aware sessions are no longer usable. 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 Aware.

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

Value: "android.net.wifi.aware.action.WIFI_AWARE_STATE_CHANGED"

EXTRA_AWARE_RESOURCES

Added in API level 33

static val EXTRA_AWARE_RESOURCES: String

Sent as a part of ACTION_WIFI_AWARE_RESOURCE_CHANGED that contains an instance of AwareResources representing the current Wi-Fi Aware resources.

Value: "android.net.wifi.aware.extra.AWARE_RESOURCES"

WIFI_AWARE_DATA_PATH_ROLE_INITIATOR

Added in API level 26

static val WIFI_AWARE_DATA_PATH_ROLE_INITIATOR: Int

Connection creation role is that of INITIATOR. Used to create a network specifier string when requesting a Aware network.

Value: 0

See Also

WIFI_AWARE_DATA_PATH_ROLE_RESPONDER

Added in API level 26

static val WIFI_AWARE_DATA_PATH_ROLE_RESPONDER: Int

Connection creation role is that of RESPONDER. Used to create a network specifier string when requesting a Aware network.

Value: 1

See Also

WIFI_AWARE_DISCOVERY_LOST_REASON_PEER_NOT_VISIBLE

Added in API level 31

static val WIFI_AWARE_DISCOVERY_LOST_REASON_PEER_NOT_VISIBLE: Int

Reason code provided in DiscoverySessionCallback.onServiceLost(PeerHandle, int) indicating that the service advertised by the peer is no longer visible. This may be because the peer is out of range or because the peer stopped advertising this service.

Value: 1

WIFI_AWARE_DISCOVERY_LOST_REASON_UNKNOWN

Added in API level 31

static val WIFI_AWARE_DISCOVERY_LOST_REASON_UNKNOWN: Int

Reason code provided in DiscoverySessionCallback.onServiceLost(PeerHandle, int) indicating that the service was lost for unknown reason.

Value: 0

Public methods

attach

Added in API level 26

open fun attach(
    attachCallback: AttachCallback, 
    identityChangedListener: IdentityChangedListener, 
    handler: Handler?
): Unit

Attach to the Wi-Fi Aware service - enabling the application to create discovery sessions or create connections to peers. The device will attach to an existing cluster if it can find one or create a new cluster (if it is the first to enable Aware in its vicinity). Results (e.g. successful attach to a cluster) are provided to the attachCallback object. An application must call WifiAwareSession.close() when done with the Wi-Fi Aware object.

Note: a Aware cluster is a shared resource - if the device is already attached to a cluster then this function will simply indicate success immediately using the same attachCallback.

This version of the API attaches a listener to receive the MAC address of the Aware interface on startup and whenever it is updated (it is randomized at regular intervals for privacy). If targeting android.os.Build.VERSION_CODES#TIRAMISU or later, the application must have android.Manifest.permission#NEARBY_WIFI_DEVICES with android:usesPermissionFlags="neverForLocation". If the application does not declare android:usesPermissionFlags="neverForLocation", then it must also have android.Manifest.permission#ACCESS_FINE_LOCATION. If targeting an earlier release than android.os.Build.VERSION_CODES#TIRAMISU, the application must have android.Manifest.permission#ACCESS_FINE_LOCATION. Apps without android.Manifest.permission#NEARBY_WIFI_DEVICES or android.Manifest.permission#ACCESS_FINE_LOCATION can use the attach(android.net.wifi.aware.AttachCallback,android.os.Handler) version. Note that aside from permission requirements the IdentityChangedListener will wake up the host at regular intervals causing higher power consumption, do not use it unless the information is necessary (e.g. for out-of-band discovery).

Parameters
`attachCallback`	AttachCallback: A callback for attach events, extended from `AttachCallback`. This value cannot be `null`.
`identityChangedListener`	IdentityChangedListener: A callback for changed identity or cluster ID, extended from `IdentityChangedListener`. This value cannot be `null`.
`handler`	Handler?: The Handler on whose thread to execute the callbacks of the `attachCallback` and `identityChangedListener` objects. If a null is provided then the application's main thread will be used.

attach

Added in API level 26

open fun attach(
    attachCallback: AttachCallback, 
    handler: Handler?
): Unit

Note: a Aware cluster is a shared resource - if the device is already attached to a cluster then this function will simply indicate success immediately using the same attachCallback.
Requires android.Manifest.permission#ACCESS_WIFI_STATE and android.Manifest.permission#CHANGE_WIFI_STATE

Parameters
`attachCallback`	AttachCallback: A callback for attach events, extended from `AttachCallback`. This value cannot be `null`.
`handler`	Handler?: The Handler on whose thread to execute the callbacks of the `attachCallback` object. If a null is provided then the application's main thread will be used.

getAvailableAwareResources

Added in API level 31

open fun getAvailableAwareResources(): AwareResources?

Return the available resources of the Wi-Fi aware service: a set of parameters which specify limitations on service usage, e.g the number of data-paths which could be created.

May return null if the Wi-Fi Aware service is not initialized. Use attach(android.net.wifi.aware.AttachCallback,android.os.Handler) or attach(android.net.wifi.aware.AttachCallback,android.net.wifi.aware.IdentityChangedListener,android.os.Handler) to initialize the Wi-Fi Aware service.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Return
`AwareResources?`	An object specifying the currently available resource of the Wi-Fi Aware service.

getCharacteristics

Added in API level 26

open fun getCharacteristics(): Characteristics?

Returns the characteristics of the Wi-Fi Aware interface: a set of parameters which specify limitations on configurations, e.g. the maximum service name length.

Return
`Characteristics?`	An object specifying configuration limitations of Aware.

getPairedDevices

Added in API level 34

open fun getPairedDevices(
    executor: Executor, 
    resultsCallback: Consumer<MutableList<String!>!>
): Unit

Get all the paired devices configured by the calling app.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Parameters
`executor`	Executor: The executor on which callback will be invoked. This value cannot be `null`.
`resultsCallback`	Consumer<MutableList<String!>!>: An asynchronous callback that will return a list of paired devices' alias This value cannot be `null`.

isAvailable

Added in API level 26

open fun isAvailable(): Boolean

Returns the current status of Aware API: whether or not Aware is available. To track changes in the state of Aware API register for the ACTION_WIFI_AWARE_STATE_CHANGED broadcast.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Return
`Boolean`	A boolean indicating whether the app can use the Aware API at this time (true) or not (false).

isDeviceAttached

Added in API level 31

open fun isDeviceAttached(): Boolean

Return the current status of the Aware service: whether or not the device is already attached to an Aware cluster. To attach to an Aware cluster, please use attach(android.net.wifi.aware.AttachCallback,android.os.Handler) or attach(android.net.wifi.aware.AttachCallback,android.net.wifi.aware.IdentityChangedListener,android.os.Handler).
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Return
`Boolean`	A boolean indicating whether the device is attached to a cluster at this time (true) or not (false).

isInstantCommunicationModeEnabled

Added in API level 31

open fun isInstantCommunicationModeEnabled(): Boolean

Return the current status of the Wifi Aware instant communication mode. If the device doesn't support this feature, return will always be false.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Return
`Boolean`	true if it is enabled, false otherwise.

See Also

android.net.wifi.aware.Characteristics#isInstantCommunicationModeSupported()

isOpportunisticModeEnabled

Added in API level 34

open fun isOpportunisticModeEnabled(
    executor: Executor, 
    resultsCallback: Consumer<Boolean!>
): Unit

Indicate whether all Wi-Fi Aware sessions created by the calling app are opportunistic as defined and configured by setOpportunisticModeEnabled(boolean)
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Parameters
`executor`	Executor: The executor on which callback will be invoked. 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.
`resultsCallback`	Consumer<Boolean!>: An asynchronous callback that will return boolean This value cannot be `null`.

isSetChannelOnDataPathSupported

Added in API level 33

open fun isSetChannelOnDataPathSupported(): Boolean

Return the device support for setting a channel requirement in a data-path request. If true the channel set by WifiAwareNetworkSpecifier.Builder.setChannelFrequencyMhz(int, boolean) will be honored, otherwise it will be ignored.
Requires android.Manifest.permission#ACCESS_WIFI_STATE

Return
`Boolean`	True is the device support set channel on data-path request, false otherwise.

removePairedDevice

Added in API level 34

open fun removePairedDevice(alias: String): Unit

Remove the target paired device setup by the caller by DiscoverySession.initiatePairingRequest(PeerHandle, String, int, String) and DiscoverySession.acceptPairingRequest(int, PeerHandle, String, int, String)
Requires android.Manifest.permission#CHANGE_WIFI_STATE

Parameters
`alias`	String: The alias set by the caller This value cannot be `null`.

resetPairedDevices

Added in API level 34

open fun resetPairedDevices(): Unit

Reset all paired devices setup by the caller by DiscoverySession.initiatePairingRequest(PeerHandle, String, int, String) and DiscoverySession.acceptPairingRequest(int, PeerHandle, String, int, String)
Requires android.Manifest.permission#CHANGE_WIFI_STATE

setOpportunisticModeEnabled

Added in API level 34

open fun setOpportunisticModeEnabled(enabled: Boolean): Unit

Set all Wi-Fi Aware sessions created by the calling app to be opportunistic. Opportunistic Wi-Fi Aware sessions are considered low priority and may be torn down (the sessions or the Aware interface) if there are resource conflicts.
Requires android.Manifest.permission#CHANGE_WIFI_STATE

Parameters
`enabled`	Boolean: True to configure all Wi-Fi Aware sessions by the calling app as Opportunistic. False by default.