Added in API level 26

Summary: Methods | Inherited Methods

DiscoverySession

---

Kotlin |Java

public class DiscoverySession
extends Object implements AutoCloseable

java.lang.Object
↳	android.net.wifi.aware.DiscoverySession

Known direct subclasses PublishDiscoverySession, SubscribeDiscoverySession PublishDiscoverySession A class representing a Aware publish session.  SubscribeDiscoverySession A class representing a Aware subscribe session.

---

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
void	acceptPairingRequest(int requestId, PeerHandle peerHandle, String peerDeviceAlias, int cipherSuite, String password) Accept and respond to a Wi-Fi Aware Pairing setup request received from peer.
void	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).
NetworkSpecifier	createNetworkSpecifierOpen(PeerHandle peerHandle) This method was deprecated in API level 29. Use the replacement WifiAwareNetworkSpecifier.Builder.
NetworkSpecifier	createNetworkSpecifierPassphrase(PeerHandle peerHandle, String passphrase) This method was deprecated in API level 29. Use the replacement WifiAwareNetworkSpecifier.Builder.
void	initiateBootstrappingRequest(PeerHandle peerHandle, int method) Initiate a Wi-Fi Aware bootstrapping setup request to create a pairing with the target peer.
void	initiatePairingRequest(PeerHandle peerHandle, String peerDeviceAlias, int cipherSuite, String password) Initiate a Wi-Fi Aware Pairing setup request to create a pairing with the target peer.
void	rejectPairingRequest(int requestId, PeerHandle peerHandle) Reject a Wi-Fi Aware Pairing setup request received from peer.
void	sendMessage(PeerHandle peerHandle, int messageId, byte[] message) Sends a message to the specified destination.

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.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Public methods

acceptPairingRequest

Added in API level 34

public void acceptPairingRequest (int requestId, 
                PeerHandle peerHandle, 
                String peerDeviceAlias, 
                int cipherSuite, 
                String password)

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 DiscoverySessionCallback.onPairingSetupRequestReceived(android.net.wifi.aware.PeerHandle, int)
peerHandle	PeerHandle: The peer's handle for the pairing request. Must be a result of a 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 Characteristics.WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_128, and 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

Added in API level 26

public void 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). 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().

createNetworkSpecifierOpen

Added in API level 26
Deprecated in API level 29

public NetworkSpecifier createNetworkSpecifierOpen (PeerHandle peerHandle)

This method was deprecated in API level 29.
Use the replacement WifiAwareNetworkSpecifier.Builder.

Create a NetworkRequest.Builder.setNetworkSpecifier(NetworkSpecifier) for an unencrypted WiFi Aware connection (link) to the specified peer. The NetworkRequest.Builder.addTransportType(int) should be set to 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.

Returns
NetworkSpecifier	A NetworkSpecifier to be used to construct NetworkRequest.Builder.setNetworkSpecifier(NetworkSpecifier) to pass to ConnectivityManager.requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback) [or other varieties of that API].

createNetworkSpecifierPassphrase

Added in API level 26
Deprecated in API level 29

public NetworkSpecifier createNetworkSpecifierPassphrase (PeerHandle peerHandle, 
                String passphrase)

This method was deprecated in API level 29.
Use the replacement WifiAwareNetworkSpecifier.Builder.

Create a NetworkRequest.Builder.setNetworkSpecifier(NetworkSpecifier) for an encrypted WiFi Aware connection (link) to the specified peer. The NetworkRequest.Builder.addTransportType(int) should be set to 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, 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.
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.

Returns
NetworkSpecifier	A NetworkSpecifier to be used to construct NetworkRequest.Builder.setNetworkSpecifier(NetworkSpecifier) to pass to ConnectivityManager.requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback) [or other varieties of that API].

initiateBootstrappingRequest

Added in API level 34

public void initiateBootstrappingRequest (PeerHandle peerHandle, 
                int method)

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)

Parameters
peerHandle	PeerHandle: The peer's handle for the pairing request. Must be a result of an DiscoverySessionCallback#onServiceDiscovered(ServiceDiscoveryInfo) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) events. This value cannot be null.
method	int: one of the AwarePairingConfig#PAIRING_BOOTSTRAPPING_ values, should be one of the methods received from ServiceDiscoveryInfo#getPairingConfig() AwarePairingConfig#getBootstrappingMethods() Value is either 0 or a combination of AwarePairingConfig.PAIRING_BOOTSTRAPPING_OPPORTUNISTIC, AwarePairingConfig.PAIRING_BOOTSTRAPPING_PIN_CODE_DISPLAY, AwarePairingConfig.PAIRING_BOOTSTRAPPING_PASSPHRASE_DISPLAY, AwarePairingConfig.PAIRING_BOOTSTRAPPING_QR_DISPLAY, AwarePairingConfig.PAIRING_BOOTSTRAPPING_NFC_TAG, AwarePairingConfig.PAIRING_BOOTSTRAPPING_PIN_CODE_KEYPAD, AwarePairingConfig.PAIRING_BOOTSTRAPPING_PASSPHRASE_KEYPAD, AwarePairingConfig.PAIRING_BOOTSTRAPPING_QR_SCAN, and AwarePairingConfig.PAIRING_BOOTSTRAPPING_NFC_READER

initiatePairingRequest

Added in API level 34

public void initiatePairingRequest (PeerHandle peerHandle, 
                String peerDeviceAlias, 
                int cipherSuite, 
                String password)

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 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 Characteristics.WIFI_AWARE_CIPHER_SUITE_NCS_PK_PASN_128, and 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

Added in API level 34

public void rejectPairingRequest (int requestId, 
                PeerHandle peerHandle)

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 DiscoverySessionCallback.onPairingSetupRequestReceived(android.net.wifi.aware.PeerHandle, int)
peerHandle	PeerHandle: The peer's handle for the pairing request. Must be a result of a DiscoverySessionCallback.onServiceDiscovered(android.net.wifi.aware.ServiceDiscoveryInfo) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) events. This value cannot be null.

sendMessage

Added in API level 26

public void sendMessage (PeerHandle peerHandle, 
                int messageId, 
                byte[] message)

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, byte[], java.util.List) 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, byte[]).

Parameters
peerHandle	PeerHandle: The peer's handle for the message. Must be a result of an DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], java.util.List) or DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[]) 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	byte: The message to be transmitted. This value may be null.