22. Session Initiation Protocol

SESSION Initiation Protocol (SIP) is a standard way to set up a call, videoconference, or other session between two network endpoints. Conceptually, SIP interactions resemble call setup in a traditional telephone network: dialing numbers, ringing, busy signals, and hanging up. However, SIP is entirely independent of the type of session that will be set up. In the traditional telephone analogy, SIP has nothing to do with the actual voice conversation.

In today’s world of relatively slow wireless data networks, SIP is slightly ahead of its time, as it is good for setting up futuristic communications such as full-motion videoconferencing and CD-quality streaming audio. However, SIP can be used to set up any type of communication, including applications like text chat that are feasible on slower networks.

One of the reasons SIP is a good fit for mobile applications is that it recognizes that people don’t use the same device all day. SIP clients can query a network of SIP servers to find a network address for a SIP user name. As a user moves from device to device during the day (from a desktop computer to a mobile phone, for example), the device can register the user’s current network address with the SIP network.

While SIP setup takes place using a network of SIP servers, the actual communication is more likely to be peer to peer. That is, two endpoints might find each other using SIP, but their actual call or videoconference could be conducted with direct network connections between the endpoints.

SIP and its close relatives are defined by Internet standard RFCs. Core SIP functionality is described in RFC 3261:

http://tools.ietf.org/html/rfc3261

For general information on SIP, try the Wikipedia entry:

http://en.wikipedia.org/wiki/Session_Initiation_Protocol

JSR 180, the SIP API for J2ME, is an optional API that enables your applications to send and receive SIP requests and responses.

22.1. Understanding SIP

SIP is a text-based protocol with similarities to HTTP and SMTP. Like HTTP, it is based around requests and responses. Like HTTP, it uses human-readable headers in both requests and responses. Many of the response codes used in SIP are similar to those in HTTP.

RFC 3261 defines six types of methods, although other standards have added more.

• REGISTER is used to associate a network address with a SIP user name.

• INVITE sends the details of a desired session to the intended recipient. The session details are described any way you want. In many cases, Session Description Protocol (SDP) is used.

• ACK is used to acknowledge a message.

• BYE ends a session.

• CANCEL stops a pending operation.

• OPTIONS queries the SIP capabilities of another device.

The JSR 180 SIP API consists of eight interfaces and four classes, all of which live in javax.microedition.sip. Like other networking APIs, the SIP API has its roots in the Generic Connection Framework.

A secure version of SIP is known as SIPS.

The following permissions are related to the SIP API:

Finally, as with other networking APIs, the push registry can be used to respond to incoming connections.

22.2. Development Tools

SIP is forward-looking technology, which means it’s hard to find devices that implement JSR 180. So far, Nokia seems to be most invested in SIP:

http://j2mepolish.org/devices/devices-sip.html

http://forum.nokia.com/main/resources/technologies/sip.html

The JSR 180 SIP API is required by MSA, so devices and applications that use the SIP API will be coming soon.

In the meantime, the Sun Java Wireless Toolkit and NetBeans Mobility offer tools for developing mobile SIP applications.

The toolkit includes an example SIP proxy and registrar server that are extremely useful when you are developing and testing an application on the emulator. To run the SIP server, choose File > Utilities… from the KToolbar menu. Select Start SIP Server and press Launch. The SIP Server will pop up in its own window. It includes a log area that displays received messages.

You can also use the toolkit’s network monitor to examine SIP traffic sent and received by the emulator.

In NetBeans Mobility, right-click on your project and choose Properties. Select Platform in the left pane, then click Manage Emulators… in the right pane. Select the Tools & Extensions tab, then click Open Utilities. Select Start SIP Server and press Launch.

22.3. Setting Up a Notifier

The first step in a SIP API application is to create a SipConnectionNotifier that will be used to handle responses and incoming requests. You can specify a listening port or use the default 5060.

This notifier is used by other parts of the SIP API. Without it, for example, you would not be able to receive a response from a request.

22.4. Sending Requests

To send a SIP request, obtain a SipClientConnection, set it up, and call its send() method.

The first step in many applications is to register in order to associate a network address with a SIP name. Here is a method that creates a REGISTER request and sends it off. The registrar argument is an IP name or address.

Notice how the SipConnectionNotifier is passed in to initRequest(). It is used to receive a response. When the response arrives, the SipClientConnectionListener is notified via its notifyResponse() method.

22.5. Receiving SIP Requests and Sending Responses

SIPConnectionNotifier also receives incoming SIP requests. Call its blocking acceptAndOpen() method to retrieve a SIPServerConnection. You can also register a SipServerConnectionListener that is notified when requests arrive.

The SIP API contains a confusing asymmetry with regard to listeners:

• SipClientConnection has an associated SipClientConnectionListener.

• SipConnectionNotifier (not SipServerConnection) has an associated SipServerConnectionListener.

You can find out the request method with getMethod() in SipServerConnection. Other methods can be used to retrieve the value of headers or to examine the payload, if there is one.

To send a response, call initResponse() and pass in the status code you wish to use.

22.6. GoSIP and SIPDemo

The Sun Java Wireless Toolkit and NetBeans Mobility Pack include two example SIP applications, both of which demonstrate different aspects of the SIP API.

• SIPDemo is the simpler of the two examples. It sends SIP messages directly between running emulators.

• GoSIP is a more realistic example (see Figure 22.1). You need two instances of the emulator and the example SIP Server. You can register as one of two users (sippy.a or sippy.b) with the example SIP Server. Then you can send an INVITE from one emulator to the other. This exchange results in a direct, peer-to-peer socket connection between the two emulators. They can then exchange text messages. A SIP BYE message terminates the conversation.

Figure 22.1. Various stages of the GoSIP example

22.7. Summary

SIP is a protocol for setting up communication sessions. It includes the same basic stages as a plain old telephone call: an invitation, ringing, talking, and hanging up. In addition, it includes a way for users to register with a SIP network, which makes it possible to locate users regardless of their current device. The JSR 180 SIP API allows MIDlets to take advantage of SIP functionality.

SipConnectionNotifier handles incoming SIP data. Use SipClientConnection to send out requests. To respond to incoming requests, get SipServerConnections from SipConnectionNotifier.

The Sun Java Wireless Toolkit and NetBeans Mobility include an example SIP proxy and registrar server that are useful for testing. The GoSIP example shows how to set up a socket-based chat session using SIP.