WifiAwareSession
open class WifiAwareSession : AutoCloseable
kotlin.Any | |
↳ | android.net.wifi.aware.WifiAwareSession |
This class represents a Wi-Fi Aware session - an attachment to the Wi-Fi Aware service through which the app can execute discovery operations.
Summary
Public methods | |
---|---|
open Unit |
close() Destroy the Wi-Fi Aware service session and, if no other applications are attached to Aware, also disable Aware. |
open NetworkSpecifier! |
createNetworkSpecifierOpen(role: Int, peer: ByteArray) Create a |
open NetworkSpecifier! |
createNetworkSpecifierPassphrase(role: Int, peer: ByteArray, passphrase: String) Create a |
open Unit |
publish(publishConfig: PublishConfig, callback: DiscoverySessionCallback, handler: Handler?) Issue a request to the Aware service to create a new Aware publish discovery session, using the specified |
open Unit |
subscribe(subscribeConfig: SubscribeConfig, callback: DiscoverySessionCallback, handler: Handler?) Issue a request to the Aware service to create a new Aware subscribe discovery session, using the specified |
Public methods
close
open fun close(): Unit
Destroy the Wi-Fi Aware service session and, if no other applications are attached to Aware, also disable Aware. This method destroys all outstanding operations - i.e. all publish and subscribes are terminated, and any outstanding data-links are shut-down. However, it is good practice to destroy these discovery sessions and connections explicitly before a session-wide destroy.
An application may re-attach after a destroy using WifiAwareManager.attach(AttachCallback, Handler)
.
Exceptions | |
---|---|
java.lang.Exception |
if this resource cannot be closed |
createNetworkSpecifierOpen
open funcreateNetworkSpecifierOpen(
role: Int,
peer: ByteArray
): NetworkSpecifier!
Deprecated: Please use in-band data-path setup, refer to WifiAwareNetworkSpecifier.Builder
, publish(android.net.wifi.aware.PublishConfig,android.net.wifi.aware.DiscoverySessionCallback,android.os.Handler)
and subscribe(android.net.wifi.aware.SubscribeConfig,android.net.wifi.aware.DiscoverySessionCallback,android.os.Handler)
Create a android.net.NetworkRequest.Builder#setNetworkSpecifier(NetworkSpecifier)
for an unencrypted WiFi Aware connection (link) to the specified peer. The android.net.NetworkRequest.Builder#addTransportType(int)
should be set to android.net.NetworkCapabilities#TRANSPORT_WIFI_AWARE
.
This API is targeted for applications which can obtain the peer MAC address using OOB (out-of-band) discovery. Aware discovery does not provide the MAC address of the peer - when using Aware discovery use the alternative network specifier method - android.net.wifi.aware.WifiAwareNetworkSpecifier.Builder
.
To set up an encrypted link use the createNetworkSpecifierPassphrase(int,byte[],java.lang.String)
API.
Parameters | |
---|---|
role |
Int: The role of this device: WifiAwareManager.WIFI_AWARE_DATA_PATH_ROLE_INITIATOR or WifiAwareManager.WIFI_AWARE_DATA_PATH_ROLE_RESPONDER Value is android.net.wifi.aware.WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_INITIATOR , or android.net.wifi.aware.WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_RESPONDER |
peer |
ByteArray: The MAC address of the peer's Aware discovery interface. On a RESPONDER this value is used to gate the acceptance of a connection request from only that peer. This value cannot be null . |
Return | |
---|---|
NetworkSpecifier! |
A NetworkSpecifier to be used to construct android.net.NetworkRequest.Builder#setNetworkSpecifier(NetworkSpecifier) to pass to android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest, * android.net.ConnectivityManager.NetworkCallback) [or other varieties of that API]. |
createNetworkSpecifierPassphrase
open funcreateNetworkSpecifierPassphrase(
role: Int,
peer: ByteArray,
passphrase: String
): NetworkSpecifier!
Deprecated: Please use in-band data-path setup, refer to WifiAwareNetworkSpecifier.Builder
, publish(android.net.wifi.aware.PublishConfig,android.net.wifi.aware.DiscoverySessionCallback,android.os.Handler)
and subscribe(android.net.wifi.aware.SubscribeConfig,android.net.wifi.aware.DiscoverySessionCallback,android.os.Handler)
Create a android.net.NetworkRequest.Builder#setNetworkSpecifier(NetworkSpecifier)
for an encrypted WiFi Aware connection (link) to the specified peer. The android.net.NetworkRequest.Builder#addTransportType(int)
should be set to android.net.NetworkCapabilities#TRANSPORT_WIFI_AWARE
.
This API is targeted for applications which can obtain the peer MAC address using OOB (out-of-band) discovery. Aware discovery does not provide the MAC address of the peer - when using Aware discovery use the alternative network specifier method - android.net.wifi.aware.WifiAwareNetworkSpecifier.Builder
.
Parameters | |
---|---|
role |
Int: The role of this device: WifiAwareManager.WIFI_AWARE_DATA_PATH_ROLE_INITIATOR or WifiAwareManager.WIFI_AWARE_DATA_PATH_ROLE_RESPONDER Value is android.net.wifi.aware.WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_INITIATOR , or android.net.wifi.aware.WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_RESPONDER |
peer |
ByteArray: The MAC address of the peer's Aware discovery interface. On a RESPONDER this value is used to gate the acceptance of a connection request from only that peer. This value cannot be null . |
passphrase |
String: The passphrase to be used to encrypt the link. The PMK is generated from the passphrase. Use createNetworkSpecifierOpen(int,byte[]) to specify an open (unencrypted) link. This value cannot be null . |
Return | |
---|---|
NetworkSpecifier! |
A NetworkSpecifier to be used to construct android.net.NetworkRequest.Builder#setNetworkSpecifier(NetworkSpecifier) to pass to android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest, * android.net.ConnectivityManager.NetworkCallback) [or other varieties of that API]. |
publish
open fun publish(
publishConfig: PublishConfig,
callback: DiscoverySessionCallback,
handler: Handler?
): Unit
Issue a request to the Aware service to create a new Aware publish discovery session, using the specified publishConfig
configuration. The results of the publish operation are routed to the callbacks of DiscoverySessionCallback
:
-
DiscoverySessionCallback.onPublishStarted(
is called when the publish session is created and provides a handle to the session. Further operations on the publish session can be executed on that object. DiscoverySessionCallback.onSessionConfigFailed()
is called if the publish operation failed.
Other results of the publish session operations will also be routed to callbacks on the callback
object. The resulting publish session can be modified using PublishDiscoverySession.updatePublish(PublishConfig)
.
The total count of currently available Wi-Fi Aware publish sessions is limited and is available via the AwareResources.getAvailablePublishSessionsCount()
method.
An application must use the DiscoverySession.close()
to terminate the publish discovery session once it isn't needed. This will free resources as well terminate any on-air transmissions.
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
.
Parameters | |
---|---|
publishConfig |
PublishConfig: The PublishConfig specifying the configuration of the requested publish session. This value cannot be null . |
callback |
DiscoverySessionCallback: A DiscoverySessionCallback derived object to be used for session event callbacks. This value cannot be null . |
handler |
Handler?: The Handler on whose thread to execute the callbacks of the callback object. If a null is provided then the application's main thread will be used. |
subscribe
open fun subscribe(
subscribeConfig: SubscribeConfig,
callback: DiscoverySessionCallback,
handler: Handler?
): Unit
Issue a request to the Aware service to create a new Aware subscribe discovery session, using the specified subscribeConfig
configuration. The results of the subscribe operation are routed to the callbacks of DiscoverySessionCallback
:
-
DiscoverySessionCallback.onSubscribeStarted(
is called when the subscribe session is created and provides a handle to the session. Further operations on the subscribe session can be executed on that object. DiscoverySessionCallback.onSessionConfigFailed()
is called if the subscribe operation failed.
Other results of the subscribe session operations will also be routed to callbacks on the callback
object. The resulting subscribe session can be modified using SubscribeDiscoverySession.updateSubscribe(SubscribeConfig)
.
The total count of currently available Wi-Fi Aware subscribe sessions is limited and is available via the AwareResources.getAvailableSubscribeSessionsCount()
method.
An application must use the DiscoverySession.close()
to terminate the subscribe discovery session once it isn't needed. This will free resources as well terminate any on-air transmissions.
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
.
Parameters | |
---|---|
subscribeConfig |
SubscribeConfig: The SubscribeConfig specifying the configuration of the requested subscribe session. This value cannot be null . |
callback |
DiscoverySessionCallback: A DiscoverySessionCallback derived object to be used for session event callbacks. This value cannot be null . |
handler |
Handler?: The Handler on whose thread to execute the callbacks of the callback object. If a null is provided then the application's main thread will be used. |