|
Router API: Device connection
|
PeerDeviceNet separates device connections setup and logical
communication groups. Device connection logic will handle security
and authentication so that no devices can be connected without
owners/users' awareness and permission. On top of device connection
topology, flexible communication groups can be formed according to
application logic and an app can participate in multiple groups.
Various Connectors / ConnectionManager can be built on top of device
connection service api to apply different security logic. Because of
the separation of device connection service and group communication
service, apps can reuse existing Connectors or ConnectinManagers to
connect their devices without bothering connection security details,
and focus on app specific group communication structure and app
logic.
PeerDeviceNet's connection service api supports the following
features:
- network detection, connection and disconnection: when device
is attached to networks or detached from networks. Currently it
supports wifi, wifi-direct and mobile hotspot. because its
plugin style implementation, it is easy to add bluetooth or
other transport.
- peer device discovery: it is designed to enable new ways of
peer discovery, for example, use new sensors in mobile devices.
On top of it we built apps using multicast, scanning QR code,
NFC tapping for peer discovery and connection.
- peer device connection, detection of connecting peers and
disconnection.
By default, an Connector or ConnectionManager using connection
service api will support intents with action names:
ACTION_CONNECTOR, ACTION_CONNECTION_MANAGEMENT. Apps can reuse
existing Connectors using the following code, as in Chat sample:
Intent intent = new
Intent("com.xconns.peerdevicenet.CONNECTION_MANAGEMENT");
startActivity(intent);
Apps using connection service 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:
"NET_TYPE","NET_NAME","NET_PASS","NET_INFO","NET_INTF_NAME","NET_ADDR","NET_INTF_MCAST".
PeerDeviceNet exposes three kinds of connection api:
- Intents api
Apps can send startService() intents
with the following action names for connection setup:
- Intent actions related to network connection info, events
and setting active network:
ACTION_GET_NETWORKS =
"com.xconns.peerdevicenet.GET_NETWORKS";
ACTION_GET_ACTIVE_NETWORK =
"com.xconns.peerdevicenet.GET_ACTIVE_NETWORK";
ACTION_CONNECT_NETWORK =
"com.xconns.peerdevicenet.CONNECT_NETWORK";
ACTION_DISCONNECT_NETWORK =
"com.xconns.peerdevicenet.DISCONNECT_NETWORK";
ACTION_ACTIVATE_NETWORK =
"com.xconns.peerdevicenet.ACTIVATE_NETWORK";
- Intent actions for searching and finding peer devices:
ACTION_START_SEARCH =
"com.xconns.peerdevicenet.START_SEARCH"
ACTION_STOP_SEARCH = "com.xconns.peerdevicenet.STOP_SEARCH"
- Intent actions for device connection setup:
ACTION_CONNECT =
"com.xconns.peerdevicenet.CONNECT"
ACTION_DISCONNECT = "com.xconns.peerdevicenet.DISCONNECT"
ACTION_ACCEPT_CONNECTION =
"com.xconns.peerdevicenet.ACCEPT_CONNECTION"
ACTION_DENY_CONNECTION =
"com.xconns.peerdevicenet.DENY_CONNECTION"
Apps should register a broadcast receiver to handle the
following connection events:
ACTION_GET_NETWORKS =
"com.xconns.peerdevicenet.GET_NETWORKS";
ACTION_GET_ACTIVE_NETWORK =
"com.xconns.peerdevicenet.GET_ACTIVE_NETWORK";
ACTION_ACTIVATE_NETWORK =
"com.xconns.peerdevicenet.ACTIVATE_NETWORK";
ACTION_NETWORK_CONNECTING =
"com.xconns.peerdevicenet.NETWORK_CONNECTING";
ACTION_NETWORK_CONNECTION_FAILED =
"com.xconns.peerdevicenet.NETWORK_CONNECTION_FAILED";
ACTION_NETWORK_CONNECTED =
"com.xconns.peerdevicenet.NETWORK_CONNECTED";
ACTION_NETWORK_DISCONNECTED =
"com.xconns.peerdevicenet.NETWORK_DISCONNECTED";
ACTION_SEARCH_FOUND_DEVICE =
"com.xconns.peerdevicenet.SEARCH_FOUND_DEVICE"
ACTION_SEARCH_COMPLETE =
"com.xconns.peerdevicenet.SEARCH_COMPLETE"
ACTION_CONNECTING = "com.xconns.peerdevicenet.CONNECTING"
ACTION_CONNECTION_FAILED =
"com.xconns.peerdevicenet.CONNECTION_FAILED"
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:
- "NET_TYPE","NET_NAME","NET_PASS","NET_INFO","NET_INTF_NAME","NET_ADDR","NET_INTF_MCAST":
info about networks this device is on
- "PEER_NAME", "PEER_ADDR", "PEER_PORT": peer device to be
connected or disconnected
- "TIMEOUT": search or connection timeout
- "AUTHENTICATION_TOKEN": a byte[] array to contain the token
for authentication
- "CONNECTION_DENY_CODE": the reason why connection is denied
by peer device.
- 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);
//connect to specified network
oneway void connectNetwork(int sessionId,
in NetInfo net);
//disconnect a specified network
oneway void disconnectNetwork(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);
//connecting to network has started
oneway void onNetworkConnecting(in NetInfo
net);
//connection to network has failed
oneway void onNetworkConnectionFailed(in
NetInfo net);
//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);
}
The recommended practice of accessing ConnectionService aidl api
is by using wrapper class
RouterConnectionClient
which also handle some common book-keeping for you. For detailed
tutorial on how to use RouterConnectionClient to talk to
ConnectionService and set up peer device connections, please
check out
github
sample project.
- 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 static final int
CONNECT_NETWORK = 10705;
public static final int
DISCONNECT_ NETWORK = 10706;
public static final int
NETWORK_CONNECTING = 10707;
public static final int
NETWORK_CONNECTION_FAILED = 10708;
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.