API: Device connection

Home   |   Features   |   Install   |   User guide   |   Developer API   |   Contact
Introduction   |   Remote intenting   |   Group communication   |   Device connection   |   Java API   |   Tutorials   |   Architecture    |   Open source

The simple way to set up connections among peer devices is to use PeerDeviceNet's connection manager, so that apps can completely avoid the code for connection setup, reuse the existing component and secure connection features, and focus on logical "communication groups" setup.

PeerDeviceNet's connection manager supports two connection strategies:

Apps can start up PeerDeviceNet's connection manager easily with the code, as in Chat sample:
Intent intent = new Intent("com.xconns.peerdevicenet.CONNECTION_MANAGEMENT");

If Apps need to set up connection in its own style, it can directly use the connection service api. Apps using connection api should add the following permission to its AndroidManifest.xml:

<uses-permission android:name="com.xconns.peerdevicenet.permission.REMOTE_MESSAGING" />

Many api methods use the folllowing class to describe network:

class NetInfo {

public int type;                 //Network type: WI-FI, WI-FI Direct, Bluetooth, ...
public String name;         //SSID or network names
public String pass;          //connection paraphrase if available
public byte[] info;            //other info
public String intfName;  //local interface name for this network
public String addr;         //addr of this device in this network
public boolean mcast;    //does it support multicast?

Correspondingly use the following key names to pack network info inside a message bundle:

PeerDeviceNet exposes three kinds of connection api:
  1. Intents api
Apps can send startService() intents with the following action names for connection setup:
ACTION_GET_NETWORKS = "com.xconns.peerdevicenet.GET_NETWORKS";
ACTION_START_SEARCH = "com.xconns.peerdevicenet.START_SEARCH"
ACTION_STOP_SEARCH = "com.xconns.peerdevicenet.STOP_SEARCH"
ACTION_CONNECT = "com.xconns.peerdevicenet.CONNECT"
ACTION_DISCONNECT = "com.xconns.peerdevicenet.DISCONNECT"

Apps should register a broadcast receiver to handle the following connection events:

ACTION_GET_NETWORKS = "com.xconns.peerdevicenet.GET_NETWORKS";
ACTION_CONNECTING = "com.xconns.peerdevicenet.CONNECTING"
ACTION_CONNECTED = "com.xconns.peerdevicenet.CONNECTED"
ACTION_DISCONNECTED = "com.xconns.peerdevicenet.DISCONNECTED"

Connection related data are packaged as intent extras using the following key names:
  1. IDL api
The IDL(aidl) interfaces related to device connection setup are defined in two files:
Apps can bind to the following named service to perform connection setup:
ACTION_CONNECTION_SERVICE = "com.xconns.peerdevicenet.ConnectionService".

Once bound, the returned service object has the following methods for connection setup:
IRouterConnectionService {
    // --- network api ---
    //get connected networks
    oneway void getNetworks(int sessionId);
    //get current network used by PeerDeviceNet for peer connections
    oneway void getActiveNetwork(int sessionId);
    //choose a network for peer connections
    oneway void activateNetwork(int sessionId, in NetInfo net);

    // --- peer device discovery/search api ---
    //during discovery/search, broadcast this device's DeviceInfo(name, addr, port) and receive peers' DeviceInfo
    //peers' search time-spans must overlap so that they can find each other
    oneway void startPeerSearch(int sessionId, int timeout);
    oneway void stopPeerSearch(int sessionId)

    // --- connection api ---
    //send connect request to a peer device with security credentials
    oneway void connect(int sessionId, in DeviceInfo peer, in byte[] token, int timeout); 
    //disconnect from a peer
    oneway void disconnect(int sessionId, in DeviceInfo peer);
    //accept a peer's connection request (so a peer-peer connection will be setup)
    oneway void acceptConnection(int sessionId, in DeviceInfo peer);
    //deny a peer's connection request
    oneway void denyConnection(int sessionId, in DeviceInfo peer, int rejectCode);

Apps will register the following handler to handle connection related events:
IRouterConnectionHandler {
    // --- network related callbacks ---
    //results of calling getNetworks()
    oneway void onGetNetworks(in NetInfo[] nets);
    //runtime detect that this device is connected to a new network
    oneway void onNetworkConnected(in NetInfo net);
    //runtime detect that this device is disconnected from a network
    oneway void onNetworkDisconnected(in NetInfo net);
    //result of calling getActiveNetwork()
    oneway void onGetActiveNetwork(in NetInfo net);
    //completion of PeerDeviceNet switching to a network for peer connections
    oneway void onNetworkActivated(in NetInfo net);

    // --- peer search/discovery callbacks ---
    //found a peer device (ie. received a peer's DeviceInfo)
    oneway void onSearchFoundDevice(in DeviceInfo device);
    //search session complete, either time out or by stopPeerSearch()
    oneway void onSearchComplete();

    // --- connection callbacks ---
    //receive a peer's connection request with its security credential
    oneway void onConnecting(in DeviceInfo device, in byte[] token);
    //my connection request to peer (identified by "device") failed with rejectCode (explicit reject by user, network fail, etc.)
    oneway void onConnectionFailed(in DeviceInfo device, int rejectCode); 
    //a peer successfully connected, either my connection request accepted or i accept peer's connect request
    oneway void onConnected(in DeviceInfo device);
    //a peer disconnected
    oneway void onDisconnected(in DeviceInfo device);
  1. Messenger api
        Apps send Messages with the following message ids for connection setup:
        public static final int GET_NETWORKS = 10700;
        public static final int GET_ACTIVE_NETWORK = 10701;
        public static final int ACTIVATE_NETWORK = 10702;
public final static int START_SEARCH = -10200;
public final static int STOP_SEARCH = -10201;
public final static int CONNECT = -10300;
public final static int DISCONNECT = -10301;
public final static int ACCEPT_CONNECTION = -10302;
public final static int DENY_CONNECTION = -10303;

Apps need to handle Messages with the following ids for connection setup:
        public static final int GET_NETWORKS = 10700;
        public static final int GET_ACTIVE_NETWORK = 10701;
        public static final int ACTIVATE_NETWORK = 10702;
        public static final int NETWORK_CONNECTED = 10703;
        public static final int NETWORK_DISCONNECTED = 10704;
public final static int SEARCH_FOUND_DEVICE = -10210;
public final static int SEARCH_COMPLETE = -10211;
public final static int CONNECTING = -10310;
public final static int CONNECTION_FAILED = -10311;
public final static int CONNECTED = -10312;
public final static int DISCONNECTED = -10313;

Connection related data are packaged as a bundle inside Message object using the same key names as intent api.