Skip to content

Latest commit

 

History

History
242 lines (184 loc) · 8.24 KB

README.md

File metadata and controls

242 lines (184 loc) · 8.24 KB
Raw

cordova-plugin-networking-multipeer

This plugin provides Multipeer Connectivity for peer to peer networking between iOS devices, using infrastructure Wi-Fi networks, peer-to-peer Wi-Fi, and Bluetooth personal area networks.

Installation

cordova plugin add cordova-plugin-networking-multipeer

Supported Platforms

  • iOS

Namespace and API

All the functions and events described in this plugin reside in the networking.multipeer namespace.

All the functions are asynchronous and have 2 callbacks as their last 2 parameters, the first being the success callback, and the second being the error callback.

All the events have the following methods:

Event.addListener(function callback)
Event.removeListener(function callback)
boolean Event.hasListener(function callback)
boolean Event.hasListeners()

Adapter information

To obtain information of the local peer, use the getLocalPeerInfo method:

var localPeer;
networking.multipeer.getLocalPeerInfo(function (peerInfo) {
    // The peerInfo object has the following properties:
    // id: Number --> A session-specific numerical ID that represents the peer
    // name: String --> The human-readable name of the peer
    // hash: Number --> A hash value that can be useful for deciding which peer should invite
    localPeer = peerInfo;
    console.log('id: ' + peerInfo.id);
    console.log('name: ' + peerInfo.name);
});

Device discovery (browsing and advertising)

To begin discovery of nearby devices, use the startBrowsing method. Discovery can be resource intensive so you should call stopBrowsing once the connection has been succesfully established.

You should call startBrowsing whenever your app needs to discover nearby devices.

Information about each newly discovered device is received using the onFoundPeer event.

If a previously discovered device is not reachable anymore, the onLostPeer event will be fired.

Example:

var device_names = {};
var last_peer_id;
var updateDeviceName = function (peerInfo) {
    device_names[peerInfo.id] = peerInfo.name;
    last_peer_id = peerInfo.id;
};

// Add listener to receive newly found devices
networking.multipeer.onFoundPeer.addListener(updateDeviceName);

// Now begin the discovery process.
var serviceType = 'xx-service'; // serviceType is a 1-15 character long string that can contain only ASCII lowercase letters, numbers, and hyphens
networking.multipeer.startBrowsing(serviceType, function () {
    // The device is now discovering
}, function () {
    // There was an error
});

// If you want to stop discovering
networking.multipeer.stopBrowsing();

To make the device discoverable, use the startAdvertising function, that will make the device discoverable.

To stop making the device discoverable, for example once all the peers have been connected, use the stopAdvertising function.

var serviceType = 'xx-service'; // serviceType is a 1-15 character long string that can contain only ASCII lowercase letters, numbers, and hyphens
networking.multipeer.startAdvertising(serviceType, function () {
    // The device is now discoverable
}, function () {
    // There was an error making the device discoverable
});

// If you want to stop advertising
networking.multipeer.stopAdvertising();

Connecting peers

With Multipeer Connectivity, the devices that are discovering (browsing) send an invitation to the devices that are discoverable (advertising), that in turn accept or decline the invitation.

In order to send an invitation, the device must be browsing, so be sure to send the invitation before calling the stopBrowsing function.

Example:

networking.multipeer.invitePeer(last_peer_id, function () {
    // The invitation has been sent, but the connection is not yet established.
    // The connection will be succesfully established once the onChangeState event
    // will be fired with the expected peer id and the 'Connected' state
}, function () {
    console.log('Invitation failed');
});

On the other end, in order to accept or decline the invitation, the device must be advertising, so be sure to have handled the invitation before calling the stopAdvertising function.

Example:

networking.multipeer.onReceiveInvitation.addListener(function (invitationInfo) {
    // invitationInfo.peerInfo --> The inviting peer
    // invitationInfo.invitationId --> The id to use for accepting or declining the invitation
    // To decline the invitation, simply call declineInvitation instead of acceptInvitation
    networking.multipeer.acceptInvitation(invitationInfo.invitationId, function () {
        // The invitation has been accepted, but the connection is not yet established.
        // The connection will be succesfully established once the onChangeState event
        // will be fired with the expected peer id and the 'Connected' state
    }, function () {
        // There was an error accepting the invitation
    });
});

OPTIONAL: In order to implement automatic connection, the devices can be both browsing and advertising at the same time, so, in order to have only one device sending the invitaton, the hash attribute can be compared like this:

networking.multipeer.onFoundPeer.addListener(function (peerInfo) {
    // When all the devices are both browsing and advertising,
    // this guarantees that only one device sends the invitation
    if (localPeer.hash > peerInfo.hash) {
        networking.multipeer.invitePeer(peerInfo.id);
    }
});

A list of the currently connected peers can always be obtained by calling the getConnectedPeers function.

networking.multipeer.getConnectedPeers(function (peers) {
    // peers is an array of peerInfo objects
    for (var i = 0; i < peers.length; i++) {
        console.log(peers[i].name);
    }
});

Receiving and sending data

Receiving and sending data uses ArrayBuffer objects.

Sending data can be done either in reliable mode, or in unreliable mode.

To send data you have in arrayBuffer use sendDataReliable or sendDataUnreliable:

// The first argument to sendDataReliable and sendDataUnreliable can be either a single
// peer id, or an array containing all the peer ids that should receive the data
networking.multipeer.sendDataReliable(last_peer_id, arrayBuffer, function (bytes_sent) {
    console.log('Sent ' + bytes_sent + ' bytes');
}, function (errorMessage) {
    console.log('Send failed: ' + errorMessage);
})

In contrast to the methods to send data, data is received in a single event (onReceiveData).

networking.multipeer.onReceiveData.addListener(function (receiveInfo) {
    // receiveInfo is an object with the following members:
    // peerInfo --> The peer who sent the data
    // data --> ArrayBuffer
    if (receiveInfo.peerInfo.id !== last_peer_id) {
        return;
    }

    // receiveInfo.data is an ArrayBuffer.
});

Receiving connection/disconnection

To be notified of peer connection/disconnection, add a listener to the onChangeState event.

networking.multipeer.onChangeState.addListener(function (stateInfo) {
    // stateInfo is an object with the following members:
    // peerInfo --> The peer whose state is changed (a complete peerInfo object, not just its id)
    // state --> A string that can contain one of the following values:
    //  'NotConnected'
    //  'Connecting'
    //  'Connected'
    if (stateInfo.peerInfo.id !== last_peer_id) {
        return;
    }

    console.log(stateInfo.state);
});

Disconnecting

To hang up the connection and disconnect use disconnect.

networking.multipeer.disconnect();