mirror of
https://github.com/hackku21/nearby_connections.git
synced 2024-10-27 19:14:01 +00:00
196 lines
7.0 KiB
Markdown
196 lines
7.0 KiB
Markdown
<img src="https://developers.google.com/nearby/images/nearby_logo.svg" align="right">
|
|
|
|
# nearby_connections
|
|
|
|
An **android** flutter plugin for the [Nearby Connections API](https://developers.google.com/nearby/connections/overview)
|
|
Currently supports Bytes and Files.
|
|
|
|
**Transfer Data between multiple connected devices using fully offline peer to peer networking**
|
|
|
|
[](https://pub.dartlang.org/packages/nearby_connections)
|
|
[](https://github.com/mannprerak2/nearby_connections)
|
|
[](https://github.com/mannprerak2/nearby_connections)
|
|
## Table of Content
|
|
* [Setup](#setup)
|
|
* [Work Flow](#work-flow)
|
|
* [Advertise For connections](#advertise-for-connection)
|
|
* [Discover Advertisers](#discover-advertisers)
|
|
* [Request Connection](#request-connection)
|
|
* [Accept Connection](#accept-connection)
|
|
* [Sending Data](#sending-data)
|
|
* [Sending Bytes Payload](#sending-bytes-payload)
|
|
* [Sending Files](#sending-file-payload)
|
|
|
|
## Setup
|
|
|
|
### Note regarding Location(GPS)
|
|
While using this,
|
|
**Location/GPS service must be turned on** or devices may disconnect
|
|
more often, some devices may disconnect immediately.
|
|
|
|
### Set Permissions
|
|
Add these to AndroidManifest.xml
|
|
```xml
|
|
<!-- Required for Nearby Connections -->
|
|
<uses-permission android:name="android.permission.BLUETOOTH" />
|
|
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
|
|
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
|
|
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
|
|
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
|
|
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
|
|
|
|
<!-- Optional: only required for FILE payloads-->
|
|
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
|
|
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
|
|
```
|
|
Since ACCESS_FINE_LOCATION and READ_EXTERNAL_STORAGE is considered to be dangerous system permissions, in addition to adding them to your manifest, you must request these permissions at runtime.
|
|
|
|
#### As a **convenience** this library provides methods to check and request location and external read/write permissions
|
|
```dart
|
|
// returns true/false asynchronously
|
|
bool a = await Nearby().checkLocationPermissions();
|
|
// asks for permission only if its not given
|
|
// returns true/false if the location permission is granted on/off resp.
|
|
bool b = Nearby().askLocationPermission();
|
|
|
|
// OPTIONAL: if you need to transfer files and rename it on device
|
|
bool b = Nearby().checkExternalStoragePermission();
|
|
// asks for READ + WRTIE EXTERNAL STORAGE permission only if its not given
|
|
Nearby().askExternalStoragePermission() ;
|
|
|
|
Nearby().askLocationAndExternalStoragePermission(); // for all permissions in one go..
|
|
```
|
|
|
|
## Work Flow
|
|
|
|
The work flow is similar to the [Android Nearby Connections library](https://developers.google.com/nearby/connections/overview)
|
|
|
|
## NOTE
|
|
|
|
**Location/GPS service must be turned on** or devices may disconnect
|
|
more often, some devices may disconnect immediately.
|
|
|
|
For convenience this library provides methods to check and enable location
|
|
```dart
|
|
bool b = await Nearby().checkLocationEnabled();
|
|
|
|
// opens dialogue to enable location service
|
|
// returns true/false if the location service is turned on/off resp.
|
|
bool b = await Nearby().enableLocationServices();
|
|
```
|
|
### Advertise for connection
|
|
```dart
|
|
try {
|
|
bool a = await Nearby().startAdvertising(
|
|
userName,
|
|
strategy,
|
|
onConnectionInitiated: (String id,ConnectionInfo info) {
|
|
// Called whenever a discoverer requests connection
|
|
},
|
|
onConnectionResult: (String id,Status status) {
|
|
// Called when connection is accepted/rejected
|
|
},
|
|
onDisconnected: (String id) {
|
|
// Callled whenever a discoverer disconnects from advertiser
|
|
},
|
|
serviceId: "com.yourdomain.appname", // uniquely identifies your app
|
|
);
|
|
} catch (exception) {
|
|
// platform exceptions like unable to start bluetooth or insufficient permissions
|
|
}
|
|
```
|
|
### Discover Advertisers
|
|
```dart
|
|
try {
|
|
bool a = await Nearby().startDiscovery(
|
|
userName,
|
|
strategy,
|
|
onEndpointFound: (String id,String userName, String serviceId) {
|
|
// called when an advertiser is found
|
|
},
|
|
onEndpointLost: (String id) {
|
|
//called when an advertiser is lost (only if we weren't connected to it )
|
|
},
|
|
serviceId: "com.yourdomain.appname", // uniquely identifies your app
|
|
);
|
|
} catch (e) {
|
|
// platform exceptions like unable to start bluetooth or insufficient permissions
|
|
}
|
|
```
|
|
### Stopping Advertising and Discovery
|
|
```dart
|
|
Nearby().stopAdvertising();
|
|
Nearby().stopDiscovery();
|
|
// endpoints already discovered will still be available to connect
|
|
// even after stopping discovery
|
|
// You should stop discovery once you have found the intended advertiser
|
|
// this will reduce chances for disconnection
|
|
```
|
|
### Request Connection
|
|
```dart
|
|
// to be called by discover whenever an endpoint is found
|
|
// callbacks are similar to those in startAdvertising method
|
|
try{
|
|
Nearby().requestConnection(
|
|
userName,
|
|
id,
|
|
onConnectionInitiated: (id, info) {
|
|
},
|
|
onConnectionResult: (id, status) {
|
|
},
|
|
onDisconnected: (id) {
|
|
},
|
|
);
|
|
}catch(exception){
|
|
// called if request was invalid
|
|
}
|
|
```
|
|
### Accept Connection
|
|
```dart
|
|
Nearby().acceptConnection(
|
|
id,
|
|
onPayLoadRecieved: (endpointId, payload) {
|
|
// called whenever a payload is recieved.
|
|
},
|
|
onPayloadTransferUpdate: (endpointId, payloadTransferUpdate) {
|
|
// gives status of a payload
|
|
// e.g success/failure/in_progress
|
|
// bytes transferred and total bytes etc
|
|
}
|
|
);
|
|
```
|
|
## Sending Data
|
|
### Sending Bytes Payload
|
|
|
|
```dart
|
|
Nearby().sendBytesPayload(endpointId, bytes_array);
|
|
|
|
// payloads are recieved by callback given to acceptConnection method.
|
|
```
|
|
### Sending File Payload
|
|
You need to send the File Payload and File Name seperately.
|
|
|
|
File is stored in DOWNLOAD_DIRECTORY and given a generic name
|
|
So you would need to rename the file on receivers end.
|
|
|
|
```dart
|
|
//creates file with generic name (without extension) in Downloads Directory
|
|
//its your responsibility to rename the file properly
|
|
Nearby().sendFilePayload(endpointId, filePath);
|
|
|
|
//Send filename as well so that receiver can rename the file
|
|
Nearby().sendBytesPayload(endpointId,fileNameEncodedWithPayloadId);
|
|
//e.g send a string like "payloadId:FileExtensionOrFullName" as bytes
|
|
|
|
//payloads are recieved by callback given to acceptConnection method.
|
|
```
|
|
Every payload has an **ID** which is same for sender and receiver.
|
|
|
|
You can get the absolute FilePath from Payload in *onPayloadReceived* function
|
|
|
|
Checkout the [**Example**](https://github.com/mannprerak2/nearby_connections/tree/master/example) in Repository for more details
|
|
|
|
|
|
|
|
|