nearby_connections

An android flutter plugin for the Nearby Connections API

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

Since ACCESS_FINE_LOCATION 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,fileNameEncoded);

// payloads are recieved by callback given to acceptConnection method.