DiscoverySession
open class DiscoverySession : AutoCloseable
kotlin.Any | |
↳ | android.net.wifi.aware.DiscoverySession |
A class representing a single publish or subscribe Aware session. This object will not be created directly - only its child classes are available: PublishDiscoverySession
and SubscribeDiscoverySession
. This class provides functionality common to both publish and subscribe discovery sessions:
- Sending messages:
sendMessage(android.net.wifi.aware.PeerHandle,int,byte[])
method. - Creating a network-specifier when requesting a Aware connection using
WifiAwareNetworkSpecifier.Builder
.
The close()
method must be called to destroy discovery sessions once they are no longer needed.
Summary
Public methods | |
---|---|
open Unit |
acceptPairingRequest(requestId: Int, peerHandle: PeerHandle, peerDeviceAlias: String, cipherSuite: Int, password: String?) Accept and respond to a Wi-Fi Aware Pairing setup request received from peer. |
open Unit |
close() Destroy the publish or subscribe session - free any resources, and stop transmitting packets on-air (for an active session) or listening for matches (for a passive session). |
open NetworkSpecifier! |
createNetworkSpecifierOpen(peerHandle: PeerHandle) Create a |
open NetworkSpecifier! |
createNetworkSpecifierPassphrase(peerHandle: PeerHandle, passphrase: String) Create a |
open Unit |
initiateBootstrappingRequest(peerHandle: PeerHandle, method: Int) Initiate a Wi-Fi Aware bootstrapping setup request to create a pairing with the target peer. |
open Unit |
initiatePairingRequest(peerHandle: PeerHandle, peerDeviceAlias: String, cipherSuite: Int, password: String?) Initiate a Wi-Fi Aware Pairing setup request to create a pairing with the target peer. |
open Unit |
rejectPairingRequest(requestId: Int, peerHandle: PeerHandle) Reject a Wi-Fi Aware Pairing setup request received from peer. |
open Unit |
sendMessage(peerHandle: PeerHandle, messageId: Int, message: ByteArray?) Sends a message to the specified destination. |
Public methods
acceptPairingRequest
open fun acceptPairingRequest(
requestId: Int,
peerHandle: PeerHandle,
peerDeviceAlias: String,
cipherSuite: Int,
password: String?
): Unit
Accept and respond to a Wi-Fi Aware Pairing setup request received from peer. This is the response to the DiscoverySessionCallback#onPairingSetupRequestReceived(PeerHandle, int)
When the Aware Pairing setup is finished, both sides will receive DiscoverySessionCallback#onPairingSetupSucceeded(PeerHandle, String)
Parameters | |
---|---|
requestId |
Int: Id to identify the received pairing session, obtained by android.net.wifi.aware.DiscoverySessionCallback#onPairingSetupRequestReceived(android.net.wifi.aware.PeerHandle,int) |
peerHandle |
PeerHandle: The peer's handle for the pairing request. Must be a result of a android.net.wifi.aware.DiscoverySessionCallback#onServiceDiscovered(android.net.wifi.aware.ServiceDiscoveryInfo) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) events. This value cannot be null . |
peerDeviceAlias |
String: The alias of paired device set by caller, will help caller to identify the paired device. This value cannot be null . |
cipherSuite |
Int: The cipher suite to be used to encrypt the link. Value is either 0 or a combination of android.net.wifi.aware.Characteristics#WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_128 , and android.net.wifi.aware.Characteristics#WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_256 |
password |
String?: The password is used for the pairing setup. If set to empty or null, opportunistic pairing will be used. |
close
open fun close(): Unit
Destroy the publish or subscribe session - free any resources, and stop transmitting packets on-air (for an active session) or listening for matches (for a passive session). The session may not be used for any additional operations after its destruction.
This operation must be done on a session which is no longer needed. Otherwise system resources will continue to be utilized until the application exits. The only exception is a session for which we received a termination callback, DiscoverySessionCallback#onSessionTerminated()
.
Exceptions | |
---|---|
java.lang.Exception |
if this resource cannot be closed |
createNetworkSpecifierOpen
open funcreateNetworkSpecifierOpen(peerHandle: PeerHandle): NetworkSpecifier!
Deprecated: Use the replacement WifiAwareNetworkSpecifier.Builder
.
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 method should be used when setting up a connection with a peer discovered through Aware discovery or communication (in such scenarios the MAC address of the peer is shielded by an opaque peer ID handle). If an Aware connection is needed to a peer discovered using other OOB (out-of-band) mechanism then use the alternative WifiAwareSession#createNetworkSpecifierOpen(int, byte[])
method - which uses the peer's MAC address.
Note: per the Wi-Fi Aware specification the roles are fixed - a Subscriber is an INITIATOR and a Publisher is a RESPONDER.
To set up an encrypted link use the createNetworkSpecifierPassphrase(android.net.wifi.aware.PeerHandle,java.lang.String)
API.
Parameters | |
---|---|
peerHandle |
PeerHandle: The peer's handle obtained through DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], java.util.List) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) . 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(
peerHandle: PeerHandle,
passphrase: String
): NetworkSpecifier!
Deprecated: Use the replacement WifiAwareNetworkSpecifier.Builder
.
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 method should be used when setting up a connection with a peer discovered through Aware discovery or communication (in such scenarios the MAC address of the peer is shielded by an opaque peer ID handle). If an Aware connection is needed to a peer discovered using other OOB (out-of-band) mechanism then use the alternative WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)
method - which uses the peer's MAC address.
Note: per the Wi-Fi Aware specification the roles are fixed - a Subscriber is an INITIATOR and a Publisher is a RESPONDER.
Parameters | |
---|---|
peerHandle |
PeerHandle: The peer's handle obtained through DiscoverySessionCallback#onServiceDiscovered(PeerHandle, or DiscoverySessionCallback#onMessageReceived(PeerHandle, . 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 the createNetworkSpecifierOpen(android.net.wifi.aware.PeerHandle) API 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]. |
initiateBootstrappingRequest
open fun initiateBootstrappingRequest(
peerHandle: PeerHandle,
method: Int
): Unit
Initiate a Wi-Fi Aware bootstrapping setup request to create a pairing with the target peer. The Aware bootstrapping request should be done in the context of a discovery session - after a publish/subscribe DiscoverySessionCallback#onServiceDiscovered(ServiceDiscoveryInfo)
event is received. The peer will check if the method can be fulfilled by AwarePairingConfig.Builder#setBootstrappingMethods(int)
When the Aware Bootstrapping setup finished, both side will receive DiscoverySessionCallback#onBootstrappingSucceeded(PeerHandle, int)
initiatePairingRequest
open fun initiatePairingRequest(
peerHandle: PeerHandle,
peerDeviceAlias: String,
cipherSuite: Int,
password: String?
): Unit
Initiate a Wi-Fi Aware Pairing setup request to create a pairing with the target peer. The Aware pairing request should be done in the context of a discovery session - after a publish/subscribe DiscoverySessionCallback#onServiceDiscovered(ServiceDiscoveryInfo)
event is received. The peer will get a callback indicating a message was received using DiscoverySessionCallback#onPairingSetupRequestReceived(PeerHandle, int)
. When the Aware Pairing setup is finished, both sides will receive DiscoverySessionCallback#onPairingSetupSucceeded(PeerHandle, String)
Parameters | |
---|---|
peerHandle |
PeerHandle: The peer's handle for the pairing request. Must be a result of a android.net.wifi.aware.DiscoverySessionCallback#onServiceDiscovered(android.net.wifi.aware.ServiceDiscoveryInfo) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) events. This value cannot be null . |
peerDeviceAlias |
String: The alias of paired device set by caller, will help caller to identify the paired device. This value cannot be null . |
cipherSuite |
Int: The cipher suite to be used to encrypt the link. Value is either 0 or a combination of android.net.wifi.aware.Characteristics#WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_128 , and android.net.wifi.aware.Characteristics#WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_256 |
password |
String?: The password used for the pairing setup. If set to empty or null, opportunistic pairing will be used. |
rejectPairingRequest
open fun rejectPairingRequest(
requestId: Int,
peerHandle: PeerHandle
): Unit
Reject a Wi-Fi Aware Pairing setup request received from peer. This is the response to the DiscoverySessionCallback#onPairingSetupRequestReceived(PeerHandle, int)
Parameters | |
---|---|
requestId |
Int: Id to identify the received pairing session, get by android.net.wifi.aware.DiscoverySessionCallback#onPairingSetupRequestReceived(android.net.wifi.aware.PeerHandle,int) |
peerHandle |
PeerHandle: The peer's handle for the pairing request. Must be a result of a android.net.wifi.aware.DiscoverySessionCallback#onServiceDiscovered(android.net.wifi.aware.ServiceDiscoveryInfo) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) events. This value cannot be null . |
sendMessage
open fun sendMessage(
peerHandle: PeerHandle,
messageId: Int,
message: ByteArray?
): Unit
Sends a message to the specified destination. Aware messages are transmitted in the context of a discovery session - executed subsequent to a publish/subscribe DiscoverySessionCallback#onServiceDiscovered(PeerHandle,
event.
Aware messages are not guaranteed delivery. Callbacks on DiscoverySessionCallback
indicate message was transmitted successfully, DiscoverySessionCallback#onMessageSendSucceeded(int)
, or transmission failed (possibly after several retries) - DiscoverySessionCallback#onMessageSendFailed(int)
.
The peer will get a callback indicating a message was received using DiscoverySessionCallback#onMessageReceived(PeerHandle,
.
Parameters | |
---|---|
peerHandle |
PeerHandle: The peer's handle for the message. Must be a result of an DiscoverySessionCallback#onServiceDiscovered(PeerHandle, or DiscoverySessionCallback#onMessageReceived(PeerHandle, events. This value cannot be null . |
messageId |
Int: An arbitrary integer used by the caller to identify the message. The same integer ID will be returned in the callbacks indicating message send success or failure. The messageId is not used internally by the Aware service - it can be arbitrary and non-unique. |
message |
ByteArray?: The message to be transmitted. This value may be null . |