com.laserscorpion.rttapp.rtp

Class RTTCall

java.lang.Object

com.laserscorpion.rttapp.rtp.RTTCall

public class RTTCall
extends java.lang.Object

RTTcall is one of the core classes, establishing the RTP session and interfacing with Omnitor's RFC 4103 implementation. It communicates in both directions with the layers above and below, amd coordinates the two RTP libraries underneath (JRTP and Omnitor t140). It receives information from the SIP layer above about how to set up the call, and then initiates the RTP session. It then continuously receives text input from above, which it places into the Omnitor buffer, to be sent by the lower layer. It also listens for incoming RT text from Omnitor's library, and passes it up to any TextListeners that are registered with it (this may be something of a layer violation, though TextListener is within the SIP package).

     --------------
     |  UI layer  |
     --------------
            |
     --------------
     | SIP layer  |  (SipClient)
     --------------
            |
     --------------
     | Call layer |  (RTTCall)
     --------------
            |
     --------------
     | RTP layer  |  (JRTP, Omnitor t140)
     --------------
 

RTTCall stores the state of one call at a time, which can be calling (outgoing), ringing (incoming), connected, or ended. A new one should be created for each logical call, since each one needs its own new RTP session. Since the state transitions are caused by user interaction or SIP messages, the upper layer needs to tell RTTCall when to change state, by calling methods such as setRinging(). State changes span layers to some extent, so the RTTCall stores some SIP requests and events involved in its own creation, for later reference when the SIP layer is sending messages within dialogs or transactions. The upper layer may therefore need to call such methods as getInviteTransaction() or getCreationEvent().

Constructor Summary

Constructors

Constructor and Description
RTTCall(android.javax.sip.message.Request creationRequest, android.javax.sip.Dialog dialog, java.util.List<TextListener> messageReceivers) Use this constructor for an outgoing call.
RTTCall(android.javax.sip.RequestEvent requestEvent, android.javax.sip.ServerTransaction transaction, java.util.List<TextListener> messageReceivers) Use this constructor for an incoming call.

Method Summary

Modifier and Type	Method and Description
void	accept(java.lang.String remoteIP, int remotePort, int localRTPPort, int t140MapNum, int t140RedMapNum) Connect an incoming call that is currently ringing.
void	addDialog(android.javax.sip.Dialog dialog) Use this to change the Dialog associated with the call, especially if one was not available at creation of the RTTCall.
void	addInviteTransaction(android.javax.sip.ClientTransaction transaction) Use this to change the ClientTransaction that was used to send the original INVITE request e.g.
void	callAccepted(java.lang.String remoteIP, int remotePort, int localRTPPort, int t140MapNum, int t140RedMapNum) Connect an outgoing call has been accepted by the remote party, to set up the RTP session according to the agreed parameters.
void	end() End a call at any stage.
boolean	equals(RTTCall otherCall) This is not a true equals() override, since it does not compare arbitrary objects.
android.javax.sip.RequestEvent	getCreationEvent() This method returns the incoming RequestEvent that created the call, if any.
android.javax.sip.message.Request	getCreationRequest() This method returns the outgoing Request that created the call, if any.
android.javax.sip.Dialog	getDialog() Get the dialog for an ongoing connected call, so as to send more messages in that dialog, for example when sending BYE.
android.javax.sip.ClientTransaction	getInviteClientTransaction() Get the ClientTransaction from the original INVITE dialog of an outgoing call.
android.javax.sip.ServerTransaction	getInviteTransaction() Get the ServerTransaction from the original INVITE dialog of an incoming call.
android.javax.sip.address.Address	getOtherParty()
boolean	isCalling()
boolean	isConnected()
boolean	isRinging()
void	resetMessageReceivers(java.util.List<TextListener> messageReceivers) Replace the existing list of TextListeners with the new one, if the list of current activities changes.
void	sendText(java.lang.String text) The most important method: send real-time text in the connected call.
void	setCalling() Set the call to the calling state, when the SIP INVITE has been sent and before the other party has sent a final response.
void	setRinging() Set the call to the ringing state after the incoming INVITE is received but before the user has accepted or declined it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RTTCall

public RTTCall(android.javax.sip.RequestEvent requestEvent,
               android.javax.sip.ServerTransaction transaction,
               java.util.List<TextListener> messageReceivers)

Use this constructor for an incoming call. The requestEvent is the incoming INVITE. The transaction is the ServerTransaction used to respond to the INVITE, for both 180 Ringing and the final response. If planning to send 180 Ringing, it must be sent already, so the ServerTransaction can be used here.

Parameters:

requestEvent - the incoming INVITE event

transaction - used to send 180 Ringing, and the final response. null if no 180 has been sent yet and therefore no transaction is used yet. In that case, only one response can be sent,

messageReceivers - the TextListeners that need to be notified when there is incoming text

RTTCall

public RTTCall(android.javax.sip.message.Request creationRequest,
               android.javax.sip.Dialog dialog,
               java.util.List<TextListener> messageReceivers)

Use this constructor for an outgoing call. Ideally you will pass in the dialog that is created for the call, but this may not be available yet, so you will need to call addDialog() in that case.

Parameters:

creationRequest - the INVITE Request sent to the other party to initiate the call

dialog - the dialog that is already created for the call is available, or null if none yet

messageReceivers - the TextListeners that need to be notified when there is incoming text

Method Detail

getInviteTransaction

public android.javax.sip.ServerTransaction getInviteTransaction()

Get the ServerTransaction from the original INVITE dialog of an incoming call. This is useful when the transaction needs to be used in responding to the INVITE, which will likely happen well after it is initially received.

Returns:

the transaction used to respond to the original INVITE, or null if none

getInviteClientTransaction

public android.javax.sip.ClientTransaction getInviteClientTransaction()

Get the ClientTransaction from the original INVITE dialog of an outgoing call. This is useful when the transaction needs to be used again in cancelling the INVITE.

Returns:

the transaction used to send the original INVITE, or null if none

addDialog

public void addDialog(android.javax.sip.Dialog dialog)

Use this to change the Dialog associated with the call, especially if one was not available at creation of the RTTCall.

Parameters:

dialog - the new Dialog to associate with the call,

addInviteTransaction

public void addInviteTransaction(android.javax.sip.ClientTransaction transaction)

Use this to change the ClientTransaction that was used to send the original INVITE request e.g. when sending that INVITE, or when sending another INVITE after authenticating

Parameters:

transaction - the new ClientTransaction to associate with the call

resetMessageReceivers

public void resetMessageReceivers(java.util.List<TextListener> messageReceivers)

Replace the existing list of TextListeners with the new one, if the list of current activities changes.

Parameters:

messageReceivers - the new TextListeners

getCreationEvent

public android.javax.sip.RequestEvent getCreationEvent()

This method returns the incoming RequestEvent that created the call, if any. This is useful in connecting the call. We need to store that event somewhere, since the call completion can only come after user interaction, which will take quite a while after the SIP event is received. Precondition: call was created by an incoming RequestEvent. If call was created by an outgoing request, will return null.

Returns:

the incoming event that created the call, or null

getCreationRequest

public android.javax.sip.message.Request getCreationRequest()

This method returns the outgoing Request that created the call, if any. This Precondition: call was created by an outgoing Request. If call was created by an incoming request, will return null.

Returns:

the outgoing Request that was sent to the other party when the call was created, if any

getDialog

public android.javax.sip.Dialog getDialog()

Get the dialog for an ongoing connected call, so as to send more messages in that dialog, for example when sending BYE.

Returns:

the dialog for the established call

equals

public boolean equals(RTTCall otherCall)

This is not a true equals() override, since it does not compare arbitrary objects. It can only be called to check equality of RTTCalls, which is based on the requests that create them.

setCalling

public void setCalling()

Set the call to the calling state, when the SIP INVITE has been sent and before the other party has sent a final response.

setRinging

public void setRinging()

Set the call to the ringing state after the incoming INVITE is received but before the user has accepted or declined it.

accept

public void accept(java.lang.String remoteIP,
                   int remotePort,
                   int localRTPPort,
                   int t140MapNum,
                   int t140RedMapNum)
            throws java.lang.IllegalStateException,
                   gov.nist.jrtp.RtpException

Connect an incoming call that is currently ringing. Call this method when the SIP interactions indicate that the other party has accepted the call and is ready to receive text. Pass in the RTP parameters agreed to in the SDP interactions. Precondition: this call is currently in the ringing state Postcondition: this call is now in the connected state, and the RTP stream is set up

Parameters:

remoteIP - the IP of the remote party for the RTP stream

remotePort - the port of the remote party for the RTP stream

localRTPPort - the local port to be used for the RTP stream

t140MapNum - the RTP payload map number corresponding to t140 in the agreed session description

t140RedMapNum - must be <= 0 if not using redundancy! This is the RTP payload map number corresponding to "red", the redundant media type, in the agreed session description

Throws:

java.lang.IllegalStateException - if no call is currently ringing

gov.nist.jrtp.RtpException - if the call can't be connected

callAccepted

public void callAccepted(java.lang.String remoteIP,
                         int remotePort,
                         int localRTPPort,
                         int t140MapNum,
                         int t140RedMapNum)
                  throws java.lang.IllegalStateException,
                         gov.nist.jrtp.RtpException

Connect an outgoing call has been accepted by the remote party, to set up the RTP session according to the agreed parameters.

Parameters:

remoteIP - the IP of the remote party for the RTP stream

remotePort - the port of the remote party for the RTP stream

localRTPPort - the local port to be used for the RTP stream

t140MapNum - the RTP payload map number corresponding to t140 in the agreed session description

t140RedMapNum - must be <= 0 if not using redundancy! This is the RTP payload map number corresponding to "red", the redundant media type, in the agreed session description

Throws:

java.lang.IllegalStateException - if no call is currently outgoing

gov.nist.jrtp.RtpException - if the call can't be connected

sendText

public void sendText(java.lang.String text)

The most important method: send real-time text in the connected call. Queued outgoing text is sent after the buffering interval, so calling this method more often than that interval will add text to the buffer. The buffering interval is short enough that a human does not notice.

Parameters:

text - the characters to send

Throws:

java.lang.IllegalStateException - if the call is not connected yet

end

public void end()

End a call at any stage. Invoking multiple times has no effect; the first invocation ends the session. This method must be called or else the RTP session will remain open.

isRinging

public boolean isRinging()

isConnected

public boolean isConnected()

isCalling

public boolean isCalling()

getOtherParty

public android.javax.sip.address.Address getOtherParty()