Introducing Android Network Intents

Android Network Intents is a library that I wrote for Lands of Ruin - a game that two friends and I are developing. To avoid a complicated network setup to play the game against a friend, we needed a way to discover games running on the local network. Android offers a Network Service Discovery (NSD) since API level 16 (Android 4.1) but we kept running into problems using it. This lead to writing this library.

What does the library do?
The library allows you to send Intents to listening clients on the local network (WiFi) without knowing who these clients are. Sender and receiver do not need to connect to each other. Therefore the library can be used to write custom discovery protocols.

Sending Intents (Transmitter)
An Intent is sent by using the Transmitter class. A TransmitterException is thrown in case of error.

Sending an Intent

Receiving Intents (Receiver)
Intents are received using the Discovery class. Once started by calling enable() the Discovery class will spawn a background thread that will wait for incoming Intent objects. A DiscoveryListener instance will be notified about every incoming Intent.

Writing a DiscoveryListener to receive events.

Starting and stoping the discovery.

Things you should know
The Intents are sent as UDP multicast packets. Unlike TCP the UDP protocol does not guarantee that a sent packet will be received and there is no confirmation or retry mechanism. Even though losing a packet only happens rarely in a stable WiFi, the library is not intended for using as a stable communication protocol. Instead you can use it to find other clients (by sending an Intent in a periodic interval) and then establish a stable TCP connection for communication.

On GitHub you can find a chat sample application using the library. While this is a convenient example, it is not a good use of the library for the reasons state above. You obviously do not want to lose chat messages.

We are using the library for almost two years in Lands of Ruin and didn't observe any problems. However the game only runs on tablets so far. In theory the library should run on all Android versions back to API level 3 (Android 1.5) but this has obviously never been tested.

You can find Android Network Intents on GitHub.