Develop an IMS SIP client on Android.

Part 1

This is a series of 3 post samples how to develop for Android using ImsInnovation.com as the IMS
SIP provider. The samples has been developed using Eclipse on Mac and Windows. The other
platform that should work equally well but without testing on it is Linux.

Preparation

First of all to develop on Android one needs the SDK.

Download
http://developer.android.com/sdk/1.1_r1/index.html
Install
http://developer.android.com/sdk/1.1_r1/installing.html

If you already have an Eclipse installation such as for example the SDS (Service Developer Studio)
Or else one can be fetched here:

http://www.ericsson.com/developer/sub/open/technologies/ims_poc/tools/sds_40
or just eclipse
http://www.eclipse.org/downloads/

Start the eclipse and install the ADT (Android Development Tools)
The smoothest way is to add it as a remote site for software updates in Eclipse
Point the IDE to search for the latest ADT under:

https://dl-ssl.google.com/android/eclipse/

The other thing that is required is to sign up for a SIP IMS account.
If you do not have this already then it can be done here:

http://developer.labs.ericsson.net/apis/mjcf/mobile-java-communication-framework-user-
provisioning

Follow the link to registration.

Sample1

The first sample will demonstrate how to build a simple chat client for SIP instant messages over
IMS. Except of showing the communication framework provided by Ericsson the sample will also
demonstrate power management and waking up the screen and releasing screen locks in Android.
At the same time for people not accustomed with Android development it will also show the event
driven style of programming for true multithreaded devices.

The first step is to download the sample bundle. Unpack it and import it into Eclipse. (File/Import
[existing project]).

Under the lib directory the file containing the ImsInnovation API should be located there after
unpacking the zip file.
There is also a bin directory with the .apk file that can be used to install the sample without
compilation.

If you just want to try out the sample and you have followed the installation instructions from the
Android SDK you should now have the adb command in your path. Start the emulator from the
SDK or plug in a real phone with the USB cable. (Windows users will have to install a drive that is
provided as part of the SDK). Now to control that everything is correct an adb command can be
used to verify that adb can talk to the emulator or the phone.

$> adb devices

List of devices attached

HT845GZ53016 device

Now by typing “adb install imsLabsSample.apk” the application will be uploaded to the device.
The primary network device is the Wireless LAN driver for the real phone and the secondary the
APN with the 3G mobile access. Now a good test is to open the built in Web browser and make sure
that it has Internet connection and fetching pages in a correct way. If that is the case then there is a
fairly good chance that the sample will work too. Now tap the arrow to expand the file view in the
Android device and locate the IMS Android Sample with the nice Ericsson icon.

Since we are developers we want to know what is happening. One good command to see what the
device is doing is to type “adb logcat”. It should attach to the device and start typing a lot of
information. If this command was ran prior to starting the sample the SIP registration to the IMS
system should be logged on the screen. The sequence is terminated by a 200 OK message on the
register at the same time that the sample GUI will display a message {IMS Connected}.
In case of error there will be no message that it failed to connect, the way it informs the user is
when an IM is to be sent then an error message that there is no message service to utilize.
Now the binary is provisioned with a demo user so there might be other running and getting
clashes. So the best thing to do is to compile your own version with a unique user ID registered to
the imsinnovation.com domain. But to just get a quick feedback and a feeling what the code does .

So a simple test is to send an instant message to yourself. Just type some message and press the
send button. The SIP message will be sent to an Ericsson basement in Sweden and hopefully come
back. Now having two clients is much more fun. But for that we need first to recompile. Since if
both uses the same user login ID the testing will not be so much fun. (But it should work too due to
SIP forking. Both the terminal that sent the message and the other terminal that just registered will
receive the message.)

Now lets look at the code and how to compile the example.

A graphical user interface element in Android is usually extending the android.app.Activity

To also include the IMS SIP communication framework we have developed an extended version of
the Activity class. Instead of extending the Activity class you should extend the
com.ericsson.labs.android.ImsActivity class.

@Link to download the javadoc

So in the sample here is how the chat service is defined:

public class ImsChat extends ImsActivity {

while the ImsActivity is defined as:

public class ImsActivity extends Activity {

Now one interesting event in the Android application life-cycle is the onCreate() function call.
It is important to understand the life cycle:
http://developer.android.com/reference/android/app/Activity.html

In order for the IMS SIP connection to be established in the right way the ImsActivity onCreate
should be overridden.

@Override
public void onCreate(Bundle savedInstanceState) {
//Call super to initialize the network and IMS connection
super.onCreate(savedInstanceState);
setContentView(R.layout.main);

//Hook up the send button generated by main.xml

sendButton = (Button) findViewById(R.id.SendButton);
sendButton.setOnClickListener(sendListener);

//Hook up the two EditText fields generated by main.xml

textMessage = (EditText) findViewById(R.id.EditMessage);
textToURI = (EditText) findViewById(R.id.EditTextToURI);
textToURI.setText("sip:[email protected]");
}

First there is a call to the base class ImsActivity, super.onCreate().

Then the R.layout is pointing out the “main” as the graphical layout to show.
It is located in the sample in the res/layout directory.

<?xml version="1.0" encoding="utf-8"?>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
>
<LinearLayout android:layout_height="wrap_content"
android:id="@+id/LinearFlatLayout"
android:layout_gravity="center_horizontal"
android:layout_width="fill_parent">
<TextView android:layout_height="wrap_content"
android:text="@string/send_to" android:layout_width="wrap_content"/>
<EditText android:layout_height="wrap_content"
android:id="@+id/EditTextToURI" android:layout_width="fill_parent"/>
</LinearLayout>
<LinearLayout android:layout_height="wrap_content"
android:id="@+id/LinearFlatLayout"
android:layout_gravity="center_horizontal"
android:layout_width="fill_parent">
<TextView android:layout_height="wrap_content"
android:layout_width="wrap_content" android:text="@string/message"/>
 <EditText android:layout_height="wrap_content"
android:layout_width="fill_parent" android:id="@+id/EditMessage"/>
</LinearLayout>
<Button android:text="@string/send" android:layout_height="wrap_content"
android:layout_width="wrap_content" android:layout_gravity="right"
android:id="@+id/SendButton"/>
</LinearLayout>

The GUI is defined in XML and all labels are stored in separate Xml file for easy
internationalization. The rest of the code in the onCreate() is to tie the graphical components with
Java objects like :

sendButton = (Button) findViewById(R.id.SendButton);

A button needs a listener while the EditText widget is pre set with the text string of our own SIP
identity. Of course the XML presentation of the GUI is not as nice as a graphical one. So the
preferred way of developing the GUI is in Eclipse ADT layout mode.

Now the next event that the software has to handle is the onLogin() event callback defined by the
ImsActivity class. Here the login credentials are provided and the unique user id and password
provisioned. In a full fledged application this values would be queried by a separate login Activity.

config.put("ImsInnovation-RegisterURI", "sip:imsinnovation.com");
config.put("ImsInnovation-ProxyURI", "sip:193.180.168.44:35060");
config.put("ImsInnovation-PubUI", "sip:[email protected]");
config.put("ImsInnovation-PriUI", "youruser");
config.put("ImsInnovation-Password", "yourpass");
config.put("ImsInnovation-Realm", "imsinnovation.com");

super.onLogin(config, "3gpp-application.com.imsinnovation.sample", false);

The config object is passed in to the function by the ImsActivity and when exited from this function
it will be used to create an ImsInnovation connection. The execution continues with the call to
super() on the ImsActivity. The first parameter is the login properties config, the second is a IARI
identifier, that could be used to deploy endpoint services on the server side but also to separate
multiple applications running on the same client. The third parameter to super is if the GUI thread
should block while setting up the communication with the IMS core. If true the GUI will be drawn
when the 200 OK on register has arrived. If false the client will be able to start typing and the GUI
will be drawn as quickly as possible. But if the user would want to send a IM before everything is
initialized we would have to put a guard against that.

Next step in the initialization is to wait for the IMS framework to get connected.
The onConnected() function is called with a reference to the ImsInnovation object.
At this point the innovation object should be fully initialized. There is actually no need to keep a
reference to it since in a event that it would change the ovveriding ImsActivity class would get the
corresponding callback function invoked like the disConnected function that is implemented in this
sample. The main parts of the code in the onConnected does the following. A ServiceListener is
implemented and a callback to PageMessageReceived is the most important part. This notifies the
client that someone has sent an IM. When a page message is received we call a helper function
alertOnMessage(), we will come back to what is does later. For now lets assume that it is delivering
the IM to the end user in a nice way. The next thing we do onConnected() is to register the created
ServiceListener with the innovation object. After that the MessageService reference is retrieved
from the service listener. This is done so that when the user presses the send GUI button we can
then create a new IM and send it.

The sending is a reaction to the registered button listener we did in onCreate(). The listener callback
onClick() is called. First of all we check if the MessageService is not null. If it is then it means that
we have initiated the framework in non blocking mode and the end user is trying to send an IM
before the core is initialized. In the other case everything is as it should be and we create and send
the IM to the part specified by the TO EditText.

messageService.sendQuickMessage(textToURI.getText().toString(),
textMessage.getText().toString() .getBytes("UTF-8"), "text/plain");

This method takes a byte array and we specify that the content is text plain. It might look
complicated but the reason for this is to enable sending other content as a quick message. A picture
or a audio clip could be other things that can be transfered in a quick message. In general it is not
recommended to transfer large content. We will show in the Android samples part 3 how a file
transfer should be set up. This should be comparable to a SMS or an MMS where a couple of
kilobytes should be no problem to transfer.

The last interesting piece of code is the alertOnMessage() function.

For just displaying a quick dialog the android.widget.Toast class is used.
There is a special caveat since all UI interactions needs to be performed by the same thread. In this
case we got the callback from the SIP stack getting an incoming IM. That means that we got it from
the socket thread and not the UI thread. It is not always easy to know but with some reasoning or
after the hard trial and error getting an exception it can be figured out.

final Activity ctx = ImsChat.this;

ctx.runOnUiThread(new Runnable() {
public void run() {
Toast.makeText(ctx, message, Toast.LENGTH_LONG).show();
}
});

The rest of the alert on message function shows how other useful Android API's can be used.
Displaying the IM when the user is looking at the screen works only for demo's. In real life the
phone is in the pocket or on your desk. The KeyguardManager is a system service that enables a
representation of the service that locks the screen so that it is not touched by mistake while in you
pocket or purse. We call :

km.inKeyguardRestrictedInputMode()

The answer yields if the screen lock is on or not. This gives us a hint if the user is interacting with
the phone or not. In the case the screen is locked we do a number of things to attract the users
attention. For that reason we are going to need two more basic Android services. The
VibratorManager to alert the end user by vibrating the phone and the power manager to wake up the
phone and turn on the back lights on the screen.
The vibrator starts buzzing in a predefined pattern :

Vibrator vibrator = (Vibrator)

getSystemService(Context.VIBRATOR_SERVICE);
long[] pattern = { 500, 200 };
vibrator.vibrate(pattern, 0);

With the Power and Keyguard we do retrieve a lock object for the two services that will allow to
wake the power and release the key lock temporarily.

wl.acquire();
kl.disableKeyguard();
try {
Thread.sleep(3500); //Alert for 3,5 sec
} catch (InterruptedException e) {}

As the code comment says the end user is alerted for 3,5 seconds. If by then it has not started to
interact the vibrator stops, the screen lock is resumed and the power goes back to the state of resting
it was in when the IM was received. It is all done by this code:

wl.release();
kl.reenableKeyguard();
vibrator.cancel();

That concludes the code part of this sample and shows how a few lines of code can make a complex
chat client with the help of the ImsInnovation.jar and the Android SDK.

There are two more files in the sample that we did not mention. One is the nice Ericsson icon
representing the application. It is stored under the res/drawable directory as icon.png

The last file is the one that is the metadata about the application and specifies how everything fits
together. That is the AndroidManifest.xml
ADT help you with generating the majority of the file.
The application is defined by this xml tag :

<application android:icon="@drawable/icon" android:label="@string/app_name">

Where also the connection to the icon is made.

Another important piece is the activity declaration under the application tag.

<activity android:name=".ImsChat" android:label="@string/app_name">

<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>

This gives the OS a hint when the application is launched the ImsChat class contains the main
activity to launch.

The last important piece are the required permissions for this application to execute.
This particular application requires 6 permissions. The first 3 are connected to the IMS SIP
framework and the ImsInnovation.jar. Without these it would not operate in a correct way.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>

The SIP stack uses IP connectivity, it also uses WIFI and prevents it from going to sleep if WIFI is
connected. While the other 3 permissions are connected to alerting the end user on incoming
messages.

<uses-permission android:name="android.permission.DEVICE_POWER"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.DISABLE_KEYGUARD"/>

Now having the code covered the next step is to build and install it. Eclipse normally builds
everything automatically. There is a strange class called com.ericsson.labs.sample.androidchat.R
It is automatically generated by the ADT plugin when the project is executed.
The best way is to right click on the project and choose the “Run As” -> Android Application
Now if the real phone is connected with USB the application will be executed on the phone. If it is
not connected a new instance of the emulator will be started by eclipse ADT and the application
installed there. There is also a way to configure ADT to ask every time where a Android Application
should be executed. In that way multiple emulators might be stared at the same time and also a real
phone connected with the USB cable. One note is that in the same menu there is an Android Tools
option. If the Export Unsigned Application Package is chosen be aware that the .apk needs to be
signed. This is the way to deliver real applications for production distribution. It needs to be signed
with a real Certificate and then it can be uploaded to Android market. The other way and how the
.apk sample file is built is using debug mode signing by the ADT plugin. The developer phones will
allow this kind of APK to be installed. The commercial phones like the T-Mobile G1 phone will not
allow installing this kind of applications. The owner of such phone must go to the phone
configuration GUI and enable experimental application support.

“Settings->Applications->Unknown sources” needs to be checked/enabled

Now when everything is crystal clear I bet the next sample we will be able to spice it up a bit.

There are some things that could be done to make this sample even more exciting and it can be
explored further and perhaps donated back to the labs portal. Here is a list of things that can be
extended:

• login page
• history window for the latest messages
• tabs for communication with multiple people
• integration the the presence buddy list
• voice signal for the incoming message

All of the above should be quite trivial extensions but for simplicity the sample should only
demonstrate the least possible set for implementing a chat IM service.

Feedback:
We welcome any feedback good or bad on the posted samples.
Another interesting feedback from the community is what kind of device and network operator was
used during the tests. The basic testing was done on the emulator and a G1 developer phone using
WLAN and 3G in the AT&T network.