Nearby API Pre-Connection Phase

DZone 's Guide to

Nearby API Pre-Connection Phase

Let's discover how the pre-connection stage works in the Nearby Connections API, which is one of the many APIs available in Google Play services.

· Integration Zone ·
Free Resource

Nearby Connections API is one of the many APIs available in Google Play services.

This framework was introduced in early 2015.
Initially, it allowed only those devices to share data, which connected to the same wifi network.
After June 2017, in version 11.0, it also made use of Wifi hotspots, Bluetooth and BLE to provide offline communication support to the devices.

Using this API, devices can advertise themselves, discover nearby devices, send connection requests to other devices, and share data after the connection is made successfully.

Now, advertising, discovering, and sending a request for connection comes under one phase called the pre-connection phase.

Once the connection is established successfully, next phase of sharing data (often termed as post-connection phase) is symmetrical i.e. there is no distinction between the advertiser and discoverer.

In this article, we are going to discuss the pre-connection phase.
We'll cover the post-connection phase in another article.

Steps of the pre-connection phase are:

1. First, advertisers need to advertise themselves.
2. Discoverers then discover the nearby advertisers.
3. Then, discoverers will send a connection request to the advertisers.
4. Once the connection request is accepted by both advertiser and discoverer, the connection is established successfully.

In nearby connections, there are two strategies for advertising and discovery.

In this strategy, there can be M advertisers and N discoverers (M may or may not be equal to N), where each device can both advertise and discover.

In this strategy, there is only one advertiser, but there can be more than one discoverer.

Depending on your use case, you can opt for a particular strategy.

Let's now discuss different steps of the pre-connection phase in detail.

Advertising and Discovery:

The devices have to call startAdvertising() method in order to advertise themselves.

The syntax of startAdvertising() method is:

        new AdvertisingOptions(STRATEGY));

The 1st parameter, userName, is the name of the advertiser.
The 2nd parameter, SERVICE_ID, is a string that uniquely identifies your app.
The 3rd parameter, connectionLifecycleCallback, is an instance of implementation class of abstract class ConnectionLifecycleCallback.
One instance of this class you need to pass in requestConnection() method also (on discoverer's side).
In the last parameter, you need to pass the desired strategy, is either P2P_STAR or P2P_CLUSTER.

To know more about this method, check this reference.

Now, if other devices want to discover this advertiser, then they need to call startDiscovery() method.

The syntax of startDiscovery() method is:

        new DiscoveryOptions(STRATEGY));

The 1st parameter, SERVICE_ID, is the same string which uniquely identifies your app.
The 2nd parameter, endpointDiscoveryCallback, is an instance of implementation class of abstract class EndpointDiscoveryCallback.
The 3rd parameter, the desired strategy, is either P2P_STAR or P2P_CLUSTER.

To know more about this method, check this reference.

Note: EndpointDiscoveryCallback class has two methods, onEndpointFound() and onEndpointLost().
As soon as an advertiser is discovered, its unique endpointID is passed as a parameter to onEndpointFound() method.
If a previously discovered advertiser has been lost, its endpointID is passed as a parameter to onEndpointLost() method.

Request for Connection:

Finally, in order for the discoverers to send a connection request to the advertiser, they need to call requestConnection() method.

The syntax of requestConnection() method is:


Here, userName and endpointId are the ones that you received in onEndpointFound() method.
connectionLifecycleCallback is the instance of implementation class of abstract class ConnectionLifecycleCallback like you passed in startAdvertising() method.

To know more about this method, check this reference.

Note : ConnectionLifecycleCallback class has two methods onConnectionInitiated() and onConnectionResult().
If the connection request from discoverer results in success, then onConnectionInitiated() method is called on both advertiser and discoverer sides.
Here, both can either accept or reject the connection.
And the result of connection (either accepted or rejected) is passed in onConnectionResult() method.

After the connection is made successfully, post-connection phase (i.e. sharing of data) starts.

api, google api, integration, location services, nearby connections api, pre-connection

Published at DZone with permission of Anuj Sarawat . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}