ASAPActivity

This library is meant to support implementing interactive Android apps. Such applications use activities.

Any activity of your application that has anything to do with ASAP, network settings must be a subclass of ASAPActivity

Constructor

ASAPActivities must be constructed with its ASAPApplication. An ASAPApplication singleton makes it very simple:

public class YourActivity extends ASAPActivity {
    public YourActivity() {
        super(YourASAPApplication.getYourASAPApplication());
    }
}

A variant is chosen in the example app. Choose this if I you want to avoid an ASAPApplication singleton.

public class ASAPExampleRootActivity extends ASAPActivity {
    public static final String ASAP_EXAMPLE_APPNAME = "ASAP_EXAMPLE_APP";
    private static ASAPApplication asapApplication;

    static {
        Collection<CharSequence> formats = new ArrayList<>();
        formats.add(ASAP_EXAMPLE_APPNAME);
        ASAPExampleRootActivity.asapApplication = new ASAPExampleApplication(formats);
    }

    public ASAPExampleRootActivity() {
        super(ASAPExampleRootActivity.asapApplication);
    }

It the same idea. Any further activity would now derive from ASAPExampleRootActivity.

Life cycle

ASAPActivity performs a number of things when a change in the life cycle happens. It bind and unbinds from the ASAPService on start/resume pause/destroy. It activates or stops issuing broadcasts. You do not have to deal with those things at all. One thing is important:

Don't forget to call the super method for each lifecycle method. We try to force you with appropriate code annotations. In case we forgot: Call super at any time, e.g.

protected void onStart() {
    super.onStart(); // really important!
}

Layer 2 network management

This library allows you to ignore nearly any detail of layer 2 connections management.

YourActivity yourActivity = ..; //

yourActivity.startBluetooth();
yourActivity.stopBluetooth();

yourActivity.startBluetoothDiscoverable();
yourActivity.startBluetoothDiscovery();

Hopefully, it is self-explaining. Bluetooth environment is started and stopped.

It is tried to re-establish a connection to paired devices in certain intervals as long as the layer 2 protocol is running.

A pairing is made by a discovery procedure, see Android Developer Guide. A device must be discoverable to be found. Devices must look for each other by initiating a discovery. Both processes can only be switched on. The shut down automatically after less then a view minutes.

Alternative protocols

We work on that. There are already some prototypical implementation in the library for Wifi Direct. We also plan to support LoRa but also Internet protocols, especially e-mail and secure channels via TOR.

Send / Receive ASAP Messages

To anybody

Your application must be able to produce a byte code message. ASAP is going to transmit this message.

// we took this name in ASAPApplication example
CharSequence appName = "application/x-mySuperAppMessenger";
// choose a uri to distingush messages within your app
CharSequence uri = "mySchema://openChat";
// your message
byte[] message = ...;
/* 
true: message will be stored and delivered as soon as possible and presumably several times
false: message will be sent over open connections and forgotten
true is the better choice.
*/
boolean persistent = true;

try {
    yourActivity.sendASAPMessage(appName, uri, message, persistent);
}
catch(ASAPException e) {
    // do something, e.g. inform users...
}

That is the very nature of ASAP. Your applications wants a message to be delivered. It tags it with application name and describes it in more details with a uri. We are in an ad-hoc environment. Your application should not need to know about current connections. One A in ASAP stands for asynchronous. Use persistent=true.

This message is sent to the ASAPService which stores it for further delivery. This message is delivered during each new peer encounter. ASAP makes sure that this delivery is made only once. (See the era concept for details.)

That's it. Receiver application will be informed with listener about newly arrived messages.

Closed channels

CharSequence appName = "application/x-mySuperAppMessenger";
CharSequence uri = "mySchema://chatAliceBob";

Collection<CharSequence> recipients = new List<>();
recipients.add("Bob"); // assumed you are Alice

yourActivity.createClosedASAPChannel(appName, uri, recipients);
byte[] message = ...;
// message would only reach Bob
yourActivity.sendASAPMessage(appName, uri, message, true);

Recipients in ASAP message can be seen as filter. Messages without a recipient list are sent to any peer. Messages with recipients are only transmitted to peers in recipient list. Think of the distributed nature of your decentralized application. There is no server anywhere. By reducing recipients to Bob this message would only be delivered to Bob. It would not put it on a server with some fancy flags asking not to read it. Alice would not send this message to Clara even if she plans to visit Bob. ASAP is like verbal communication. This message would only be sent to Bob directly. Our peer has to encounter Bob to deliver this message. That's secure. And this should your application be aware of.

createClosedASAPChannel defines that each further message with appNameand uri would only be delivered to one of the peers in the recipient list.

We can implement marvellous and nearly unbreakable applications with this.

Direct interacting with ASAPStorage

Advanced topic. [TODO]

Message encryption

Advanced topic. [TODO]

receiving an asap message

Actually, ASAPService received a message in an ASAP session most probably in an ad-hoc network. The service stores this message and notifies listeners about a new arrival.

ASAPApplication encapsulates that process. It is assumed, you have implemented a class that derives from ASAPApplication. You can now add an ASAPMessageReceivedListener listeners with it.

ASAPApplication yourASAPApp = ...;
ASAPMessageReceivedListener listener = ...;
yourASAPApp.addASAPMessageReceivedListener("yourURI", listener);

The listener has to implement a single method void asapMessagesReceived(ASAPMessages messages);

The parameter provides access to a number of (in that case newly arrived) messages, see ASAPMessages

Example

This repository contains an example which was implemented for testing purpose only, see example package and namely ASAPExampleActivity

SN2 is going to become a decentralized messager based on asap.