nearby_connections/README.md

nearby_connections

An android flutter plugin for the Nearby Connections API Currently supports Bytes and Files.

Table of Content

• Setup
• Work Flow
  • Advertise For connections
  • Discover Advertisers
  • Request Connection
  • Accept Connection
• Sending Data
  • Sending Bytes Payload
  • Sending Files

Setup

Set Permissions

Add these to AndroidManifest.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 convinience the library provides methods to check and request location permissions

// returns true/false asynchronously 
bool a = await Nearby().checkPermissions()

// asks for permissions only if its not given
Nearby().askPermission()

Work Flow

The work flow is similar to the Android Nearby Connections library

Advertise for connection

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: (id) {
        // Callled whenever a discoverer disconnects from advertiser
        },
    );
} catch (exception) {
    // platform exceptions like unable to start bluetooth or insufficient permissions 
}

Discover Advertisers

try {
    bool a = await Nearby().startDiscovery(
        userName,
        strategy,
        onEndpointFound: (String id,String name, 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 )
        },
    );
} catch (e) {
    // platform exceptions like unable to start bluetooth or insufficient permissions
}

Stopping Advertising and Discovery

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

// 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

Nearby().acceptConnection(
    id,
    onPayLoadRecieved: (endid,Uint8List bytes) {
        // called whenever a payload is recieved.
    },
);

Sending Data

Sending Bytes Payload

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.

//creates file with generic name (without extension) in Downloads Directory
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:FileExtensionOrName" 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

Check Example in Repository for more details