The application is running on top of the Java Virtual Machine (JVM), and comprises the following components:

Next we describe the interfaces between the different components.

Interface between Softphone1GUI and Softphone1Listener

This interface is used for three purposes:

• to let Softphone1GUI communicate the user interface events (e.g., user presses a button) to Softphone1Listener

• to let Softphone1GUI communicate the softphone configuration to Softphone1Listener

• to let Softphone1Listener instruct Softphone1GUI to render status information on the screen

For the first purpose, the custom userInput() method is used:

void userInput(int type, String destination)

It has two arguments:

• type: It is an integer value that represents the type of GUI action that has occurred.

  • type = 0: user presses “Yes” button.

  • type = 1: user presses “No” button.

  • type = 2: user presses “Off” button.

• destination: It is a String that represents the destination address input by the user. It makes sense only when type = 0; in other cases, its value will be ignored by Softphone1Listener.

For the second purpose, we use two methods invoked on Softphone1 Listener:

Sphone1Listener(Configuration conf,Sphone1GUI GUI)
void updateConfiguration(Configuration conf)

• the Softphone1Listener() constructor method that is invoked when the user presses the “On” button and triggers the creation of a new instance of Softphone1Listener.

• The updateConfiguration() method that is invoked whenever the user presses the “Apply Configuration” button in the configuration area, typically after the user changes some configuration parameters. This method causes Softphone1Listener to update the class variables that store the soft-phone configuration parameters.

Both methods include a Configuration object that encapsulates the soft-phone configuration. The Configuration class is described in Section 12.5, “Implementation Aspects.” Additionally, the Softphone1Listener constructor method also includes as an argument a reference to the Softphone1GUI object so that, later on, Softphone1Listener can invoke the methods described next for the “third purpose.”

For the third purpose, we use a method invoked on Softphone1GUI:

void showStatus(String text)

The showStatus() method is used to display status information (represented by the text argument) on the soft-phone user interface, such as phone is ringing, call is established, and so on.

This interface is shown in Figure 12.2.

Figure 12.2. 

Interface between Softphone1Listener and the SDPManager

This interface offers two methods:

byte[] createSdp(SdpInfo sdpinfo)
SdpInfo getSdp(byte[] content)

• createSDP(): Creates an SDP message based on the key relevant parameters for the application.

• getSDP(): Obtains the relevant SDP parameter for the application from a SDP message.

This interface is shown in Figure 12.3.

Figure 12.3. 

Interface between Softphone1Listener and the VoiceTool

This interface is used for Softphone1Listener to instruct VideoTool to start/stop transmission or reception of voice streams.

The following methods are used that were explained in Chapter 11:

• int startMedia(String peerIP,int peerPort,int recvPort, int fmt)

• void stopMedia()

This interface is shown in Figure 12.4.

Figure 12.4. 

Interface between Softphone1Listener and the VideoTool

This interface is used for Softphone1Listener to instruct VideoTool to start/stop transmission or reception of voice streams.

For this purpose, the following methods are used that were explained in Chapter 11:

• int startMedia (String peerIP,int peerPort,int recvPort, int fmt)

• void stopMedia()

This interface is shown in Figure 12.5.

Figure 12.5. 

Interface between Softphone1Listener and the TonesTool

This interface is used for Softphone1Listener to instruct TonesTool to play a ringing tone or an alerting signal during the call-establishment phase if needed.

The following methods are used that were explained in Chapter 11:

• void prepareTone (String filename)

• void playTone ()

• void stopTone()

As a summary of the architecture topic, Figure 12.6 shows the different components in our application and the interfaces between them.

Figure 12.6. 

The user interaction area contains a number of components that allow the user to switch on/off the soft-phone as well as to place and release calls. The components are described next.

The configuration/display area is located at the rightmost part of the GUI. It consists of a JTabbedPane with two tabs. The first tab is the tracer display, where the signaling messages sent or received by the soft-phone will be shown in realtime. This is depicted in Figure 12.8.

Figure 12.8. 

The other tab contains the configuration area (shown in Figure 12.9), which is itself divided into two parts. The topmost half is the user configuration area. It includes a number of configuration parameters related to the user or to the UA. These parameters need to be filled in before the soft-phone is started (i.e., before “On” is pressed). Once the phone has been started, these parameters cannot be changed. These parameters are:

Figure 12.9. 

The bottom most half of the configuration tab contains media-related parameters. These can be changed at any time. In order for the changes to take effect, we need to press the button “Apply media configuration.” The changes will be effective from the next placed or received call. These parameters are:

The configuration tab of our soft-phone is shown in Figure 12.9.

This is the state the soft-phone enters when it is switched on (“On” button is pressed). It represents absence of active calls. The phone is ready to originate or receive calls. Whenever calls are completed, the phone comes back to the IDLE state.

This state is entered when the phone sends an INVITE, and is not left until it receives a provisional or final response.

In this state, a provisional response to an INVITE has been received, and the phone is waiting for the final response.

This state represents the situation where the call is active and the session fully established between the two peers.

This is the state produced when a call has been received and a 180 provisional response has been generated, but the call has not yet been accepted.

This state represents the situation where a call has been accepted, but the ACK message has not yet been received.

The soft-phone configuration is entered by the user in the configuration area of the user interface. At phone start-up, or whenever the user presses the “Apply Configuration” button, the configuration parameters are conveyed, as a Configuration object to Softphone1Listener in the userInput() or updateConfiguration() methods.

The Configuration class is just a data structure to hold the parameters entered by the user:

public class Configuration {
   int sipPort=5060;
   String name=" ";
   String userID=" ";
   int audioPort=40000;
   int videoPort=50000;
   int audioCodec=3;
   int videoCodec=26;
   public Configuration() {}
   public void setSipPort(int sp) { sipPort=sp;}
   public void setName(String nm) {name=nm;}
   public void setUserID(String UID) {userID=UID;}
   public void setAudioPort(int AP) {audioPort=AP;}
   public void setVideoPort(int VP) {videoPort=VP;}
   public void setAudioCodec(int AC) {audioCodec=AC;}
   public void setVideoCodec(int VC) {videoCodec=VC;}

   public int getSipPort() {return sipPort;}
   public String getName() {return name;}
   public String getUserID() {return userID;}
   public int getAudioPort() {return audioPort;}
   public int getVideoPort() {return videoPort;}
   public int getAudioCodec () {return audioCodec;}
   public int getVideoCodec () {return videoCodec;}
}

A situation where the media configured by the user is “Audio only” is represented by giving the videoPort field in the Configuration object a value of – 1.

On the other hand, the configuration parameters are stored in Softphone1Listener in the following class variables:

private int myPort; // this represents the SIP UDP port
private int myAudioPort;
private int myVideoPort;
private int myAudioCodec;
private int myVideoCodec;

Again, if myVideoPort=-1, it means that the user has configured “Audio only” media.

When the calling user presses the “No” button while in the WAIT_FINAL state, his or her soft-phone generates a CANCEL request. JAIN SIP offers the createCancel() method in order to create a CANCEL request from the original client transaction that the user wants to cancel. Once the CANCEL has been created, we will need to get a new client transaction through which we will send the CANCEL request:

Request myCancelRequest = myaClientTransaction.createCancel();
ClientTransaction myCancelClientTransaction =
  mySipProvider.getNewClientTransaction(myCancelRequest);
myCancelClientTransaction.sendRequest();

The called user will receive the CANCEL request while in the RINGING state. At that point, his or her phone must terminate the INVITE transaction with a 487 (Request terminated) response, after which it must respond to the CANCEL transaction itself with a 200 OK:

ServerTransaction myCancelServerTransaction=
  requestReceivedEvent.getServerTransaction();
Request originalRequest=myServerTransaction.getRequest();
Response myResponse=
  myMessageFactory.createResponse(487,originalRequest);
myServerTransaction.sendResponse(myResponse);
Response myCancelResponse=
  myMessageFactory.createResponse(200,myRequest);
myCancelServerTransaction.sendResponse(myCancelResponse);

Tags in the From and the To header, together with the CallID, are used to identify a SIP dialog. The tag in the From header is set by the calling UA, and provides only half of the dialog identification. The other half is set by the recipient of the request by including a tag in the To header of provisional and successful final responses.^[5] RFC 3261 states that UAs need to compute the tag in such a way that it is globally unique and cryptographically with at least 32 bits of randomness. The actual algorithm for generating a tag is implementation-specific.

In previous examples, we always used the same tags in the From and To header. Readers may want to enhance their soft-phone implementation by generating truly random tags. A possible option is to use the SecureRandom class provided in the standard java. security package. This class provides a cryptographically strong pseudo-random number generator. The following code generates a set of random bytes.

numBytes == 4; //adequate for the From/To tag;
byte[] rand = new byte[numBytes];
SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
random.nextBytes(bytes);

In order to use it in the From or To header we would need to convert the byte array into a string that is safe to use in SIP headers. We could, for instance, use Base64 encoding. There are a number of open source Base64 encoders that readers may use.

As we said at the beginning of this chapter, our soft-phone application is very simplified. This is also reflected in the simplicity of the state model that we are using. This call model is not catering for all the possible error conditions and timeout situations. More specifically, this state model does not respond to timeout events in the transaction layer. This means that when timers in the transaction layer expire, the transaction is terminated, but the application takes no specific action.

The state model also reflects the situation that the application is not taking care of any message retransmission whatsoever. As was explained in Chapter 7, the transaction sublayer takes care of retransmissions at that level. End-to-end retransmissions of INVITE, 200 OK, and ACK are handled by the JAIN SIP dialog implementation as corresponds to the fact that the SipStack property RETRANSMISSON_FILTER is set to ON.^[6] Regarding the INVITE transaction, there is, though, one aspect not specifically addressed by the JAIN SIP spec that the application therefore needs to implement. This refers to the situation when a UAS keeps sending retransmissions of the 200 OK response to an INVITE, but it does not receive any ACK. RFC 3261 states that the UAS core (in our case, it will be the dialog object) keeps retransmitting the 200 OK responses for 64*T1^[7] seconds, after which, if no ACK was received, the UAS needs to terminate the session by sending a BYE. This particular behavior is implemented in the state model by the explicit consideration of state WAIT_ACK and its associated timer.

The following code shows how this timeout situation is implemented in our application.

First we create a class in the declaration section of Softphone1Listener that extends the abstract class TimerTask. In its run() method, we include all the code that needs to be executed when the timer expires:

class MyTimerClass extends TimerTask {
   Softphone1Listener myListener;
   public void MyTimerTask (Softphone1Listener myListener){
      this.myListener=myListener;
   }
   public void run() {
      Request myBye=myListener.myDialog.createRequest("BYE");
      myBye.addHeader(myListener.myContactHeader);
      myListener.myClientTransaction=
      myListener.mySipProvider.getNewClientTransaction(myBye);
      myListener.myDialog.sendRequest(myListener.myClientTransaction);
   }
}

In addition to defining this class, we also need to start the timer when a transition occurs from the RINGING state to the WAIT_ACK state. That is, we need to add the following code if the YES button is pressed when in the RINGING state:

new Timer().schedule(new MyTimerTask(this),60000);

Another important assumption in the soft-phone implementation is the fact that it will not support more than one simultaneous call. During the process of call management, there will be one main transaction (either INVITE or BYE) that refers to the existing call. There may also be a parallel CANCEL transaction in case the user has tried to abort the call before it is established. In those cases where the user releases a call and immediately initiates another one, it may happen, if transport conditions are not good, that the new INVITE transaction starts before the BYE transaction is terminated (200 OK received). The soft-phone implementation will not be aware of those situations—it will just let the transaction sublayer decide when the transaction needs to be finalized. From the application point of view, the only transaction to worry about is the new one.

So we will define the following object variables at class level to refer to the main transaction at every moment in time:

We will also use the following variables to represent the parallel CANCEL transaction, if one exists:

Another aspect in our soft-phone application that is different from the practices done so far in the book is the reception of 4XX responses, such as the 486 (Busy Here) response that the soft-phone will receive if the called party is busy or rejects the incoming call. When such a response is received, the underlying client transaction implementation will automatically generate an ACK request, therefore our application does not need to bother with that aspect.

[RFC 3264] describes the SDP offer/answer model. Among other things, it describes possible options to activate the media reception and transmission at the different steps in the model. The approach that we will be taking is based on the following considerations:

This is depicted in Figure 12.13.

Figure 12.13. 

Additionally, we make some assumptions^[8] as to the way the SDP is configured and manipulated by the soft-phone. These assumptions allow us to simplify the code and to focus on the fundamental concepts. Next we describe in detail the different aspects of SDP and media handling. At each step, we will highlight the assumptions that we have made.

In order to manipulate the SDP, we will use the SdpManager class, which was introduced in Chapter 9. Likewise, in order to handle the media, the classes VoiceTool and VideoTool, which were described in Chapter 11, will be utilized.

In any case, in order not to complicate the soft-phone implementation, we do not include code for the cases where the execution of startMedia() fails. It is left as an exercise to the reader to add the necessary code that causes the soft-phone to move to IDLE if these methods fail.

offerInfo=new SdpInfo();
offerInfo.setIpAddress(myIP);
offerInfo.setAudioPort(myAudioPort);
offerInfo.setAudioFormat(myAudioCodec);
offerInfo.setVideoPort(myVideoPort);
offerInfo.setVideoFormat=(myVideoCodec);
ContentTypeHeader contentTypeHeader=
  myHeaderFactory.createContentTypeHeader("application,""sdp");
byte[] content=mySdpManager.createSdp(offerInfo);
myRequest.setContent(content,contentTypeHeader);

byte[] cont=(byte[]) myRequest.getContent();
offerInfo=mySdpManager.getSdp(cont);

ContentTypeHeader contentTypeHeader=
myHeaderFactory.createContentTypeHeader("application, ""sdp");
byte[] content=mySdpManager.createSdp(answerInfo);
myResponse.setContent(content,contentTypeHeader);
myVoiceTool.startMedia(offerInfo.getIpAddress(),offerInfo.
  getAudioPort(),answerInfo.
   getAudioPort(),offerInfo.getAudioFormat());
if (answerInfo.getVideoPort()>0) {
   myVideoTool.startMedia(offerInfo.getIpAddress(),offer
     Info.getVideoPort(),
      answerInfo.getVideoPort(),offerInfo.getVideoFormat());
}

byte[] cont=(byte[]) myResponse.getContent();
answerInfo=mySdpManager.getSdp(cont);
myVoiceTool.startMedia(answerInfo.getIpAddress(),answerInfo.
  getAudioPort(),offerInfo
   .getAudioPort(),answerInfo.getAudioFormat());
if (answerInfo.getVideoPort()>0) {
   myVideoTool.startMedia(answerInfo.getIpAddress(),answer
     Info.getVideoPort(),
      offerInfo.getVideoPort(), answerInfo.getVideoFormat());
}

We also need, in our soft-phone implementation, to stop media transmission and reception as soon as a BYE request is sent or received.

If the soft-phone is in established state and it receives a BYE request, then we need to add the following code:

myVoiceTool.stopMedia();
if (answerInfo.getVideoPort()>0) {
   myVideoTool.stopMedia();
}

Likewise, when the soft-phone is in established state and the user presses “No,” the soft-phone will send a BYE request. In addition to that, we need to stop the media session. So we must again include the same code as before:

myVoiceTool.stopMedia();
if (answerInfo.getVideoPort()>0) {
   myVideoTool.stopMedia();
}

Our soft-phone will need to play an alerting signal when an INVITE is received, or play a ringing tone when it receives a 180 Ringing provisional answer. For that purpose, we will use the TonesTool class, which we built in Chapter 11.

As soon as the soft-phone is started, we will create two instances of TonesTool: one for the alerting signal, and the other for the ringing tone. Additionally, we will prepare the DataSource objects by calling the prepareTone() method, passing as an argument a string that represents the location of the file containing the audio tone.

Thus, in the Softphone1Listener’s constructor method, we will include:

myAlertTool=new TonesTool();
myRingTool=new TonesTool();
myAlertTool.prepareTone("file://c:\alert.wav");
myRingTool.prepareTone("file://c:\ring.wav");

The alert.wav and ring.wav files MUST be present in the c:\ root directory, otherwise the program execution will fail.

The alerting signal will be played by the called party,s soft-phone when an INVITE is received in IDLE state:

myAlertTool.playTone();

In order to stop the alerting signal, we will include the following code:

myAlertTool.stopTone();

in the following situations:

The ringing signal will be played by the calling party’s soft-phone when a 180 provisional response is received in either the WAIT_PROV or WAIT_FINAL states:

myRingTool.playTone();

In order to stop the ringing signal, we will include the following code:

myRingTool.stopTone();

in the following situations:

The full code for the application can be downloaded from the book’s web page (see Appendix A).

Figure 12.14 shows a snapshot of two communicating user agents. In this case, both user agents are running in the same machine, but with different ports. Although this is an approach that allows us to look at the signaling exchanges, it does not allow us to experience the media side. For a full-fledged, end-to-end scenario also including the media, two PCs are needed, one for each user agent.

Figure 12.14.