Introduction

ECS 152B Project 2

Introduction

We have developed a SIP stack and program on top of it in project 1. In project 2, we will see how we can utilize this SIP stack to develop software on the Android platform. In addition, we will utilize a special feature of the SIP stack to implement a seamless handoff.

Terms

• 
  UA:
  

User agent, an entity that communicates through SIP

• 
  URI:
  

An identifier for SIP UA

Example: sip:ta@ pc12.cs.ucdavis.edu

• 
  SIP message:
  

All the messages that used for sip communication, like INVITE, 200, etc.

• 
  SIP dialog:
  

A p2p communication between two UAs, it is setup by INVITE, 200 and ACK, torn down by BYE and 200.

• 
  Session:
  

Established with a SIP dialog, a session is the direct communication between two UAs, directed by SIP dialog. Session messages are not related to SIP messages.

Requirement Overview

Before developing our application, we will improve and port our SIP stack from project 1. This SIP stack will have a more formal message format as well as a better support for multiple users. Moreover, we will add a handover function to the SIP stack, which means the SIP stack will be able to handle IP change during a SIP session.

Improve the SIP stack

The SIP stack for project 1 is improved to have the following requirements:

Example scenario

Alice Bob

| |

| INVITE F1 |

|----------------------->|

| 180 Ringing F2 |

|<-----------------------|

| |

| 200 OK F3 |

|<-----------------------|

| ACK F4 |

|----------------------->|

| Session |

|<======================>|

| |

| BYE F5 |

|<-----------------------|

| 200 OK F6 |

|----------------------->|

| |

Message format

Here is the new SIP message format we should use, each line is ended by a CRLF (\r\n)

1. 
   The first line: method name, callee’s URI, protocol used.
   
2. 
   Via:
   

Transport (only UDP used in this project),

responds address where the sender is expecting response. As one can see we are not fixing the 5060 port anymore, and the source address of an incoming message doesn’t matter anymore.

branch is to identify a request and its responds (a invite and its 1xx 200 have the same branch, a bye and its 200 have the same branch. ACK has a different branch.)

3. 
   To: Callee’s URI (to tag for messages other than INVITE, generated by callee after got invite)
   
4. 
   From: Caller’s URI and From tag (generated by caller, so it is not present in the initial INVITE messages)
   
5. 
   Call-ID: unique call id (UUID@host name)
   
6. 
   Type of the content(payload), ecs152b is what we use for this project, defined below
   
7. 
   Length of the payload (in byte)
   
8. 
   Empty line
   
9. 
   Start of you content, for ecs152b protocol it is transport ip:port (note that not every message contains content)
   

Call-ID, from tag and to tag together identifies a call (dialog)

1. 
   INVITE
   

INVITE sip:[e-mail] SIP/2.0

Via: SIP/2.0/UDP client.atlanta.example.com:5060;branch=z9hG4bK74bf9

From: sip:[e-mail];tag=9fxced76sl

To: sip:[e-mail]

Call-ID: [e-mail]

Content-Type: application/ecs152b

Content-Length: 151

UDP atlanta.example.com:61234

2. 
   180 Ringing
   

SIP/2.0 180 Ringing

Via: SIP/2.0/UDP client.atlanta.example.com:5060;branch=z9hG4bK74bf9

From: sip:[e-mail];tag=9fxced76sl

To: sip:[e-mail];tag=8321234356

Call-ID: [e-mail]

Content-Length: 0

3. 
   200 OK
   

SIP/2.0 200 OK

Via: SIP/2.0/UDP client.atlanta.example.com:5060;branch=z9hG4bK74bf9

From: sip:[e-mail];tag=9fxced76sl

To: sip:[e-mail];tag=8321234356

Call-ID: [e-mail]

Content-Type: application/ecs152b

Content-Length: 147

UDP biloxi.example.com:10023

4. 
   ACK
   

ACK sip:[e-mail] SIP/2.0

Via: SIP/2.0/UDP client.atlanta.example.com:5060;branch=z9hG4bK74bd5

From: sip:[e-mail];tag=9fxced76sl

To: sip:[e-mail];tag=8321234356

Call-ID: [e-mail]

Content-Length: 0

5. 
   The test scenario described later.
   

6. 
   BYE
   

BYE sip:[e-mail] SIP/2.0

Via: SIP/2.0/UDP client.biloxi.example.com:5060;branch=z9hG4bKnashds7

From: sip:[e-mail];tag=8321234356

To: sip:[e-mail];tag=9fxced76sl

Call-ID: [e-mail]

Content-Length: 0

7. 
   200
   

SIP/2.0 200 OK

Via: SIP/2.0/UDP client.biloxi.example.com:5060;branch=z9hG4bKnashds7

From: sip:[e-mail];tag=8321234356

To: sip:[e-mail];tag=9fxced76sl

Call-ID: [e-mail]

CSeq: 1 BYE

Content-Length: 0

Change Port message

Your SIP stack should be able to handle IP/port change during the session without terminate you session. This can be consider as a case of mobility management. For example, when the mobile device moves to a WiFi coverage area, a vertical handoff happens from the cellar network and the WiFi network. What you are implementing provides seamless handoff from a user’s point of view.

The UA who changed IP/port will send an INVITE message (same call-ID) again with the new IP/port in the payload.

The other UA will respond with 200 (no 180 used here). The following messages in this session are handling with new IP/port pair.

Alice Bob

| |

| INVITE F1 |

|----------------------->|

| 180 Ringing F2 |

|<-----------------------|

| |

| 200 OK F3 |

|<-----------------------|

| ACK F4 |

|----------------------->|

| session |

|<======================>|

| |

|INVITE (change IP/port) |

|----------------------->|

| 200 OK |

|<-----------------------|

| |

| Session |

|<======================>|

| |

| BYE F5 |

|<-----------------------|

| 200 OK F6 |

|----------------------->|

| |

Session protocol

(ecs152b protocol)

After one UA received 200 for its INVITE to another UA and sent out an ACK, a session is confirmed. Let’s call the UA sent the INVITE caller, and the UA sent 200 callee. In the caller’s INVITE message, the content will contain session information similar to the following:

UDP atlanta.example.com:61234

This means the caller will be expecting UDP messages send to IP atlanta.example.com at port 61234. Also the 200 message sent by the callee will have a similar message:

UDP biloxi.example.com:10023

This has a similar meaning: the callee is expecting UDP messages at this IP and port.

So after session is confirmed, all session message should be sent to the IP/port the other party designated in this SIP dialog, unless there is an INVITE message. The new INVITE messages for a dialog may arrive at any time after the first INVITE message. With this new INVITE and its 200 responds, the two UAs can exchange information about the new IP/port they would use for this session from now on. Then the SIP stack should inform the session software layer about this change, so that a proper change can be made to assure seamless handoff.

Android User Interface

Preliminaries

For people who is new to Android, please read the following tutorials. We will cover Android in discussion session, but Android involves new programming paradigm you may not familiar with, so some practice is necessary.

• 
  Eclipse with Android ADT
  

http://developer.android.com/guide/developing/eclipse-adt.html

• 
  Android fundamentals
  

http://developer.android.com/guide/topics/fundamentals.html

• 
  Debugging
  

http://developer.android.com/guide/developing/debug-tasks.html

http://developer.android.com/guide/developing/tools/adb.html

• 
  Tutorials
  

http://developer.android.com/resources/tutorials/hello-world.html

http://developer.android.com/resources/tutorials/views/index.html

http://developer.android.com/resources/tutorials/notepad/index.html

• 
  Emulator (especially networking setup)
  

http://developer.android.com/guide/developing/tools/emulator.html#emulatornetworking

Android Testing and Debugging in Emulator

Since we do not have Android hardware for everyone, the Android application you developed should be tested in the emulator came with the Android SDK. When you read the tutorials above please pay attention to the following two aspects above:

1. 
   Android android.util.Log and DDMS can be used to print out and view trace messages during run time.
   
2. 
   When you expecting incoming messages to the application inside an emulator, you should use port forwarding on the emulator, which has been explained in the tutorial. Basically, say remote machine is sending messages to your host at port 5060, your host machine IP is 31.10.10.10, and you application is listening on port 20001, then you should make a port forwarding from 31.10.10.10:5060 to emulator’s 20001 port. Which can be done by:
   

telnet localhost 5554 (5554 might change if this is the second emulator running on the system)

now you are in the Emulator Console:

redir add udp:5060:20001

Since there is no easy way for the application inside the emulator to know the IP address of its host machine, in the Android application a setup UI is needed for the user to enter the IP address of the host machine.

As you can see, to the other SIP applications, the SIP message will be send to the 5060 port in the above example, and they don’t really care or need to know about the port 20001. So when you construction SIP messages, think about which IP address and port you are going to fill in the via field.

UI Requirements

Your application has following UI, each one is an Activity in Android.

0. 
   Setup UI
   
1. 
   Caller UI
   
2. 
   Ringing UI
   
3. 
   Callee UI
   

Setup UI

In this UI, you can enter the IP address of your host machine, and start your SIP application from there.

Caller UI

You need to develop a very simple Android Activity with basic UI with the following 3 elements:

1. 
   A ListView in which shows all the messages sent and received, with its incoming or outgoing port number/IP.
   
2. 
   Two EditText to enter test server’s IP/ port number.
   
3. 
   A Button to start calling the server.
   

Ringing UI

When called by (received an INVITE message), you should reply 180 and display a ringing UI, in there you should have a button to answer the call.

Callee UI

After answering a call from the test server, you application should show Callee UI. Where CAPTCHA question from server is displayed and you can answer this question manually.

Test Scenario

Please note that all the thick lines represent a group of SIP messages, and a thin line represents a single session message. For example the call thick line represents exchange of INVITE, 200 and ACK messages.

Without further note, all session messages are just one line message encoded in ISO-8859-1 charset, ended with one CRLF.

In the first session, your application calls Test Server, test server give you a pass phrase, you then reply with the pass phrase capitalized.

In the second scenario, Test Server will call you. Then test server sends you a string, which should be read by a human, and the human types in the answer which is sent back to server. If all correct, server will send “id”, you then can send your student id to server.

An IP/port change may be issued by server anytime during the sessions.

TESTING AND Submission

Although you are only required to submit the Android SIP application, for this project, you are responsible for testing your own code, which means you need to program both your program and the test server. In this way, you are encouraged to develop your software in a better way. You are encouraged to make the SIP stack independent of your upper layer software. If you have a fully functional SIP stack ready, developing both the application and the test server would be very easy.

Testing

As we briefly talked about in the discussion session, testing is not a one phase process. Do not start testing after you think you finished the whole program. Test early and test often, make sure all the existing code does what they intent to before moving on. It is might be a good idea to develop and verify your SIP functions first. After project 1, I think everyone should have a pretty good idea about how to do socket, client server and p2p programming. Start by extends your SIP protocol first.

After you have a fully functional SIP stack compatible with this specification, you can start writing your session classes. Remember these classes will be used by the Android application later. Make sure they work well as a functional component.

The last step will be incorporating existing functions with your Android UI code. The debugging in Android can be a little different. So make sure your code is mostly stable before dive into the Android world.

Please note that the test server and your application are not that different. Despite of the names, they are both UA program on a network, which means they are both a peer on a p2p network, they both can call each other to setup a new session, and messages are send both ways in the session. Only difference is that once you have a session confirmed, their message content and order are different.

Submission

We will have an interactive grading for project 2, however it is very important for you to submit the right file beforehand.

Let’s assume your student id is 991234567. When creating your Android application, your project should be named 991234567, with Application name as 991234567, package name as edu.ucdavis.s991234567. The build target should be Android 1.5.

Make sure that your program properly close ports and other resources.

Similar to project 1, you are required to submit the following two items:

1. 
   The zip of containing your Android application project folder.
   
2. 
   The .apk file of your application which can be directly run on a 1.5 emulator.
   

For interactive grading your application will be running against a test server, and IP/port change is possible anytime. Passing the test will gave your full credit, otherwise your score will be based on the following points: (all points requires showing running results in UI including console, we do not have time to read code in interactive grading)

1. 
   Functional p2p (sending and receiving messages and output to UI)
   
2. 
   Proper SIP stack messages parsing ( sent well formatted messages to server, parse incoming message well, find proper return address etc. from message, and output to UI)
   
3. 
   Proper SIP dialog functions (correct state machine with correct message responds to the server)
   
4. 
   Correct session state machine
   
5. 
   Correct UI (3 of them) with functional buttons and views.