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.
If you are interested in the implementation details, download the source code from GitHub. The following will elaborate on the development process of Nearby Connection.
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.
- The broadcaster calls
startBroadcasting()to start broadcasting.
- The discoverer calls
startScan()to start scanning for nearby devices.
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.
- The discoverer calls requestConnect() to initiate a connection request to the broadcaster.
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.
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.
- After the connection is set up, both endpoints can call
sendData()to send data to the remote endpoint.
- 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.
- 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.
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:
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.
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.
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.
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.
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
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.
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
DataCallback to receive data.
2.6.1 Data Types
You can call
Data.fromBytes() to create a data object of the
The following is the sample code for sending byte arrays:
Note: The size of byte arrays cannot exceed 32 KB.
The following is the sample code for receiving byte arrays:
Note: Different from data of
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.
You can call
Data.fromFile() to create a data object of the
The following is the sample code for sending a file:
To be more efficient, you can create a FILE type using ParcelFileDescriptor, which minimizes file replication.
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.
You can call
Data.fromStream() to create a data object of the
onTransferUpdate() callback is successful, the subscriber can call
streamData.asStream().asParcelFileDescriptor() to obtain the stream object.
2.6.2 Updating the Data Transmission Progress
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
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.
Using Nearby Connection, you can implement the following functions for your app:
- 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.
- 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.