{{announcement.body}}
{{announcement.title}}

Implementing Nearby Data Transmission for Your App

DZone 's Guide to

Implementing Nearby Data Transmission for Your App

Nearby Connection allows users to transfer data in forms like text, streams, and files. Use cases include multi-player gaming, real-time collaboration, etc.

· Web Dev Zone ·
Free Resource

Imagine these scenarios. When you transfer a file to your friend using a mobile phone, the progress seems never to reach the end. Finally, the transfer ends, but a single file has exhausted your mobile data. Or you are on a flight with your friends and feel bored, but you cannot play a multi-player game together because there is no Internet connection.

You are so near, yet you cannot transmit data to each other's device conveniently. Nearby Service is designed to help you resolve these pain points. You only need to integrate it, its Nearby Connection capability will allow your users to transfer data in forms like text, streams, and files. Typical use cases of this capability include multi-player gaming, real-time collaboration, multi-screen gaming, and offline file transfer.

The following figure shows how the function works.

Bob wants to chat with Lisa


If you are interested in the implementation details, download the source code from GitHubThe following will elaborate on the development process of Nearby Connection.

Scanning for connection workflow


1. Service Process

The process can be divided into four phases.

Broadcast and scanning phase: The broadcaster starts broadcasting, and the discoverer starts scanning to discover the broadcaster.

  1. The broadcaster calls startBroadcasting() to start broadcasting.
  2. The discoverer calls startScan() to start scanning for nearby devices.
  3. The onFound() method notifies the scanning result.

Connection setup phase: The discoverer initiates a connection and starts a symmetric authentication process, and the two endpoints independently accept or reject the connection request.

  1. The discoverer calls requestConnect() to initiate a connection request to the broadcaster.
  2. After onEstablish() notifies the two endpoints of the connection startup, the two endpoints can call acceptConnect() to accept the connection or call rejectConnect() to reject the connection.
  3. The onResult() method notifies the two endpoints of the connection result. The connection can be set up only when both endpoints accept the connection.

Data transmission phase: After the connection is set up, the two endpoints start data exchange.

  1. After the connection is set up, both endpoints can call sendData() to send data to the remote endpoint.
  2. The data subscriber is notified by onReceived() that the data is received. Both endpoints are notified by onTransferUpdate() of the current transmission status.

Disconnection phase: Either endpoint initiates a disconnection request to notify the remote endpoint of the disconnection.

  1. The endpoint that actively disconnects from the remote endpoint calls disconnect() to disconnect from the remote endpoint. The remote endpoint is notified by onDisconnected() of the disconnection.

2. Development Procedure

2.1 Getting Started

If you are new to Huawei Mobile Services (HMS), you need to configure app information in AppGallery Connect, enable Nearby Service on the HUAWEI Developers console, and integrate the HMS Core SDK. For details, please refer to the documentation.

2.2 Declaring System Permissions

To use Nearby Discovery and Nearby Transfer APIs in Nearby Connection development scenarios, your app must declare the appropriate permissions based on the policies used. For example, to use the POLICY_STAR policy to develop a file transfer app, you need to add specific permissions to the AndroidManifest.xml file.

XML

The ACCESS_FINE_LOCATION, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE permissions are dangerous system permissions, so you must dynamically apply for these permissions. If any required permission is not available, Nearby Service will reject the application to enable broadcast or scanning.

2.3 Selecting a Policy

Nearby Discovery supports three connection policies: POLICY_MESH, POLICY_STAR, and POLICY_P2P. You can select a policy based on the actual scenario.

The sample code for selecting a policy and creating the BroadcastOption object is as follows:

Java

2.4 Broadcast and Scanning

Once you grant the permissions required by the app and select a policy for your app, you can start broadcast and scanning to find nearby devices.

2.4.1 Starting Broadcast

The broadcaster uses the selected policy and serviceId parameters to call startBroadcasting() to start broadcasting. The serviceId parameter uniquely identifies your app. You are advised to use the package name of your app as the value of serviceId, for example, com.huawei.example.myapp.

Sample code:

Java
 


connectCallback is a connection listening callback class instance that notifies you with the connection status. For details about the connectCallback class and sample code, please refer to section 2.5.2.

2.4.2 Starting Scanning

The discoverer uses the selected policy and serviceId parameters to call startScan() to start scanning to discover nearby devices.

Sample code:

Java
 


In the preceding information, scanEndpointCallback is a scanning listening callback class instance that notifies the discoverer of the scanning result, for example, a device is discovered or a device is lost.
Java
 

2.4.3 Stopping Broadcast

To stop broadcast, you can call stopBroadcasting(). The broadcaster may still receive a connection request from the discoverer afterward.

2.4.4 Stopping Scanning

To stop scanning, you can call stopScan(). The discoverer can still request a connection to a discovered device afterward. Generally, once you find the device you want to connect to, call stopScan() to stop scanning.

2.5 Connection Setup

2.5.1 Requesting a Connection

When nearby devices are found, the discoverer can call requestConnect() to initiate connections.

Sample code:

Java
 

You can show the list of discovered devices to users and allow them to choose which devices to connect to based on your requirements.

2.5.2 Confirming the Connection

After the discoverer requests to set up a connection with the broadcaster, the discoverer notifies the two parties of the connection setup by calling back the onEstablish() method of connectCallback. Both parties must accept the connection by calling acceptConnect() or reject the connection by calling rejectConnect(). The connection can be set up only when both endpoints accept the connection. If one or both of them choose to reject the connection, the connection fails. In either mode, the connection result is notified through the onResult() method.

Sample code:

Java
 

This example shows a way for both parties to accept the connection automatically. You can use other methods to confirm the connection as required.

2.5.3 Verifying the Connection

Your app can provide a way for users to confirm the connection to a specified device. For example, you can use an authentication token, which may be a short random character string or number. Typically, this involves displaying the token on two devices and requiring the user to enter or confirm the token manually, similar to a Bluetooth pairing dialog box.

The following describes how to authenticate the connection by confirming the pairing code in a dialog box.

Sample code:

Java
 

2.6 Transmitting Data

After devices are connected, data objects can be transmitted through the connection. Data objects are classified into byte arrays, files, and streams. You can call sendData() to send data and call onReceived() of DataCallback to receive data.

2.6.1 Data Types

BYTES 

You can call Data.fromBytes() to create a data object of the Data.Type.BYTES type.

The following is the sample code for sending byte arrays:

Java
 

Note: The size of byte arrays cannot exceed 32 KB.

The following is the sample code for receiving byte arrays:

Java

Note: Different from data of FILE and STREAM types, data of the BYTES type is sent as chunks, and the subscriber does not need to wait for the TRANSFER_STATE_SUCCESS status code. When onReceived() is called, you can call data.asBytes() to obtain the full data.

FILE

You can call Data.fromFile() to create a data object of the Data.Type.FILE type.

The following is the sample code for sending a file:

Java

To be more efficient, you can create a FILE type using ParcelFileDescriptor, which minimizes file replication.

Sample code:

Java

When a file is received, it is saved in the Download directory on the subscriber's device with the name defined as the character string converted by fileData.getId(). After the transmission is complete, you can obtain the FILE object.

Sample code:

Java

STREAM

You can call Data.fromStream() to create a data object of the Data.Type.STREAM type.

Sample code:

Java
 

When the onTransferUpdate() callback is successful, the subscriber can call streamData.asStream().asInputStream() or streamData.asStream().asParcelFileDescriptor() to obtain the stream object.

Sample code:

Java
 

2.6.2 Updating the Data Transmission Progress

The onTransferUpdate() method in the DataCallBack callback class provides the data sending or receiving progress update. Both parties can display the transmission progress to users in forms like a progress bar.

2.6.3 Canceling Data Transmission

To cancel the transmission during data receiving or sending, you can call the cancelDataTransfer() method of the TransferEngine class.

2.7 Disconnecting From the Remote Endpoint

To disconnect from the remote endpoint, you can call the disconnect() method of the DiscoveryEngine class. Once this API is called, this endpoint cannot send or receive data.

Conclusion

Using Nearby Connection, you can implement the following functions for your app:

  1. Local multi-player gaming: Players can connect with each other's device flexibly and enjoy a smooth gaming experience enabled by low-latency, stable, and reliable data transmission.
  2. Offline file transfer: Files can be transferred at a speed of up to 80 Mbit/s without consuming any mobile data.


If you are interested and want to learn more, check our development guide.

Topics:
android, integration, internet connection, mobile, opensource, tutorial

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}