cnrg.itx.signal
Class DesktopSignaling

java.lang.Object
  |
  +--cnrg.itx.signal.DesktopSignaling

public class DesktopSignaling
extends java.lang.Object

The primary Signaling Object that allows the application to access all telephony services.


Inner Class Summary
 class DesktopSignaling.Result
          Inner Class containing the result of a Dial Sequence.
 
Field Summary
protected  SignalingObserver myApp
          Application's (that implements SignalingObserver) Handle
protected  java.util.Hashtable myConnectionList
          Hashtable of all Signal connections
protected  long myConnSeqNumber
          Unique sequence number
protected  java.lang.String myDesc
          Description of application
protected  cnrg.itx.ds.DirectoryService myDirS
          Directory Service Handle
protected  cnrg.itx.signal.DesktopSignalingServer myDSS
          DesktopSignalingServer Handle
protected  java.net.InetAddress myIAdd
          IP Address in InetAddress format
protected  cnrg.itx.ds.Location myLoc
          Location of this machine; Used by Server Thread, DS & App.
protected  java.lang.String myName
          String representation of IP Address
protected  cnrg.itx.ds.Password myPassword
          user's password
protected  int myServerPort
          Port Server Thread will listen on.
protected  cnrg.itx.ds.UserID myUID
          email address or phone number
protected static int TIMEOUT
          Timeout value for all Signaling Sockets using TCP
 
Constructor Summary
DesktopSignaling(SignalingObserver so, java.lang.String uid, java.lang.String pass)
          Constructor for a DesktopSignaling component for an application with no specified description and config file.
DesktopSignaling(SignalingObserver so, java.lang.String uid, java.lang.String pass, java.lang.String desc, java.lang.String config)
          Constructor for DesktopSignaling with an app description and config file for Directory Service
 
Method Summary
 SignalConnection Dial(java.lang.String userid)
          Dials a peer application and returns a SignalConnection containing the connection object to use for communication.
 SignalConnection Dial(java.lang.String userid, cnrg.itx.datax.Channel cInput, cnrg.itx.datax.Channel cOutput)
          Returns a SignalConnection containing the connection object to use for communication.
 SignalConnection Dial(java.lang.String userid, cnrg.itx.ds.Location userLoc, cnrg.itx.datax.Channel cInput, cnrg.itx.datax.Channel cOutput, SignalConnectionObserver sco)
          Returns a SignalConnection containing the connection object to use for communication.
 SignalConnection Dial(java.lang.String userid, cnrg.itx.ds.Location userLoc, SignalConnectionObserver sco)
          Returns a SignalConnection containing the connection object to use for communication.
 cnrg.itx.ds.DirectoryService getDirectory()
          This method allows application to get a handle to a ready-to-use Directory Service.
 cnrg.itx.ds.LocationList getLocationList(java.lang.String userid)
          This method allows an application to get a list of possible locations for a given user.
 int getTimeout()
          This method returns the timeout value currently being used for socket connections by Signaling.
protected  void handleAliveInvite(AliveSignalEvent ase, java.net.Socket s)
          This method is used to handle an alive request.
protected  void handleDialInvite(InviteSignalEvent ise, java.net.Socket so)
          This method is used to handle an incoming call.
protected  void handleHangupInvite(HangupSignalEvent hse, java.net.Socket s)
          This method is used to handle a hangup request.
protected  void handlePeerNotAlive(SignalConnection sc)
          This method is used to clear up resources if the peer application is no longer active.
protected  void handleSendDTMFInvite(DTMFSignalEvent dtmfse, java.net.Socket s)
          This method is used to handle an incoming DTMF tone.
 void Hangup(SignalConnection sc)
          Hangs up a given SignalConnection being used for a call.
 boolean isAlive(SignalConnection sc)
          This method queries a peer application to check if it is still running.
 void logout()
          This method unregisters the Signaling Component with Directory Services and kills the server thread.
protected  void Register()
          This method registers the DesktopSignaling Component with DirectoryService.
 void sendDTMF(java.lang.String s, SignalConnection sc)
          This method sends a DTMF tone, as a string, to the destination on a given SignalConnection
protected  java.net.Socket sendNewPacket(SigPacket send, java.lang.String ip, int p)
          This method sends a packet over a TCP connection.
protected  void sendPacket(SigPacket send, java.net.Socket sock)
          This method sends a packet over an TCP socket.
protected  void setServerPort(int p)
          The DesktopSignalingServer thread uses this method to register its port with DesktopSignaling.
 void setTimeout(int t)
          This method allows the application to set the timeout value to use for socket connections.
protected  DesktopSignaling.Result tryDialSequence(cnrg.itx.ds.UserID destUID, cnrg.itx.ds.Location destAdd, cnrg.itx.datax.Connection ac)
          This method performs a Dial Sequence including the 3-way handshake.
protected  int unRegister()
          This method Unregisters the DesktopSignaling Component on DirectoryService.
protected  SigPacket waitForPacket(java.net.Socket sock)
          This method waits for a packet on a given TCP socket.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

myUID

protected cnrg.itx.ds.UserID myUID
email address or phone number

myPassword

protected cnrg.itx.ds.Password myPassword
user's password

myDesc

protected java.lang.String myDesc
Description of application

myName

protected java.lang.String myName
String representation of IP Address

myDirS

protected cnrg.itx.ds.DirectoryService myDirS
Directory Service Handle

myDSS

protected cnrg.itx.signal.DesktopSignalingServer myDSS
DesktopSignalingServer Handle

myApp

protected SignalingObserver myApp
Application's (that implements SignalingObserver) Handle

myConnectionList

protected java.util.Hashtable myConnectionList
Hashtable of all Signal connections

myConnSeqNumber

protected long myConnSeqNumber
Unique sequence number

myIAdd

protected java.net.InetAddress myIAdd
IP Address in InetAddress format

myLoc

protected cnrg.itx.ds.Location myLoc
Location of this machine; Used by Server Thread, DS & App.

myServerPort

protected int myServerPort
Port Server Thread will listen on.

TIMEOUT

protected static int TIMEOUT
Timeout value for all Signaling Sockets using TCP
Constructor Detail

DesktopSignaling

public DesktopSignaling(SignalingObserver so,
                        java.lang.String uid,
                        java.lang.String pass)
                 throws cnrg.itx.ds.DirectoryServiceException
Constructor for a DesktopSignaling component for an application with no specified description and config file.
Parameters:
so - the SignalingObserver handle for the Application
uid - the UserID of the user
pass - the password of the user
Throws:
cnrg.itx.ds.DirectoryServiceException -  
See Also:
DirectoryServiceException

DesktopSignaling

public DesktopSignaling(SignalingObserver so,
                        java.lang.String uid,
                        java.lang.String pass,
                        java.lang.String desc,
                        java.lang.String config)
                 throws cnrg.itx.ds.DirectoryServiceException
Constructor for DesktopSignaling with an app description and config file for Directory Service
Parameters:
so - the SignalingObserver handle for the Application
uid - the UserID of the user
pass - the password of the user
desc - the String representing the type of application instantiating this component
config - is the name of the configuration file to use for Directory Service
Throws:
cnrg.itx.ds.DirectoryServiceException -  
See Also:
DirectoryServiceException
Method Detail

Dial

public SignalConnection Dial(java.lang.String userid)
                      throws cnrg.itx.datax.DataException,
                             DesktopSignalingException,
                             cnrg.itx.ds.DirectoryServiceException
Dials a peer application and returns a SignalConnection containing the connection object to use for communication. This dial is blocking. It automatically tries all locations for the given user and returns the first established connection.
Parameters:
userid - the String representing the email address or phone number or userID to call
Returns:
a SignalConnection object for data transfer
Throws:
DesktopSignalingException -  
cnrg.itx.datax.DataException -  
cnrg.itx.ds.DirectoryServiceException -  
See Also:
SignalConnection, DataException, DesktopSignalingException, DirectoryServiceException

Dial

public SignalConnection Dial(java.lang.String userid,
                             cnrg.itx.datax.Channel cInput,
                             cnrg.itx.datax.Channel cOutput)
                      throws cnrg.itx.datax.DataException,
                             DesktopSignalingException,
                             cnrg.itx.ds.DirectoryServiceException
Returns a SignalConnection containing the connection object to use for communication. This dial is blocking. It automatically tries all locations for the given user and returns the first established connection. The application provides the input and output channels to use for the call.
Parameters:
userid - the String representing the email address or phone number or userID to call
cInput - Input Channel to add to result
cOutput - Output Channel to add to result
Returns:
a SignalConnection object for data transfer
Throws:
DesktopSignalingException -  
cnrg.itx.datax.DataException -  
cnrg.itx.ds.DirectoryServiceException -  
See Also:
SignalConnection, DataException, DesktopSignalingException, DirectoryServiceException

Dial

public SignalConnection Dial(java.lang.String userid,
                             cnrg.itx.ds.Location userLoc,
                             SignalConnectionObserver sco)
                      throws cnrg.itx.datax.DataException,
                             DesktopSignalingException,
                             cnrg.itx.ds.DirectoryServiceException
Returns a SignalConnection containing the connection object to use for communication. This dial is non-blocking and requires the application to implement the SignalConnectionObserver interface. The method returns immediately with a SignalConnection. The SignalConnection can then be used to control the call (eg. startCall, abortCall etc.)
Parameters:
userid - the String representing the email address or phone number or userID to call
userLoc - the Location object that needs to be dialed.
sco - the SignalConnectionObserver object that is used by the application to control the dial process
Returns:
a SignalConnection object for the call.
Throws:
DesktopSignalingException -  
cnrg.itx.datax.DataException -  
cnrg.itx.ds.DirectoryServiceException -  
See Also:
SignalConnectionObserver, SignalConnection, DataException, DesktopSignalingException, DirectoryServiceException

Dial

public SignalConnection Dial(java.lang.String userid,
                             cnrg.itx.ds.Location userLoc,
                             cnrg.itx.datax.Channel cInput,
                             cnrg.itx.datax.Channel cOutput,
                             SignalConnectionObserver sco)
                      throws cnrg.itx.datax.DataException,
                             DesktopSignalingException,
                             cnrg.itx.ds.DirectoryServiceException
Returns a SignalConnection containing the connection object to use for communication. This dial is non-blocking and requires the application to implement the SignalConnectionObserver interface. This method allows the app to specify the input and output channels to use for data exchange. The method returns immediately with a SignalConnection. The SignalConnection can then be used to control the call (eg. startCall, abortCall etc.)
Parameters:
userid - the String representing the email address or phone number or userID to call
userLoc - the Location object that needs to be dialed
cInput - the input channel to use for data exchange
cOutput - the output channel to use for data exchange
sco - the SignalConnectionObserver object that is used by the application to control the dial process
Returns:
a SignalConnection object for the call.
Throws:
DesktopSignalingException -  
cnrg.itx.datax.DataException -  
cnrg.itx.ds.DirectoryServiceException -  
See Also:
SignalConnectionObserver, SignalConnection, DataException, DesktopSignalingException, DirectoryServiceException

Hangup

public void Hangup(SignalConnection sc)
            throws ConnectException
Hangs up a given SignalConnection being used for a call.
Parameters:
sc - the SignalConnection to hangup
Returns:
void
Throws:
ConnectException -  

sendDTMF

public void sendDTMF(java.lang.String s,
                     SignalConnection sc)
              throws ConnectException
This method sends a DTMF tone, as a string, to the destination on a given SignalConnection
Parameters:
s - is the string representation of the DTMF tone.
sc - is the SignalConnection currently in use with the peer application.
Returns:
void
Throws:
ConnectException -  

isAlive

public boolean isAlive(SignalConnection sc)
                throws ConnectException
This method queries a peer application to check if it is still running. If the peer application does not respond then the data connection between them is closed and removed.
Parameters:
sc - is the SignalConnection currently in use with the peer application.
Returns:
TRUE if the application is still running, FALSE otherwise
Throws:
ConnectException -  

getDirectory

public cnrg.itx.ds.DirectoryService getDirectory()
This method allows application to get a handle to a ready-to-use Directory Service. The application needs to know the Directory Service API.
Parameters:
None. -  
Returns:
A handle to a DirectoryService Object

getLocationList

public cnrg.itx.ds.LocationList getLocationList(java.lang.String userid)
                                         throws cnrg.itx.ds.DirectoryServiceException
This method allows an application to get a list of possible locations for a given user. This should be used in conjuntion with the non-blocking dial to call specific locations.
Parameters:
userid - is the String representation of a user.
Returns:
A LocationList for the given userid.
Throws:
cnrg.itx.ds.DirectoryServiceException -  

setTimeout

public void setTimeout(int t)
This method allows the application to set the timeout value to use for socket connections.
Parameters:
t - is the timeout in milliseconds to be used for Sockets.
Returns:
void

getTimeout

public int getTimeout()
This method returns the timeout value currently being used for socket connections by Signaling.
Parameters:
None -  
Returns:
the integer value of the timeout

logout

public void logout()
This method unregisters the Signaling Component with Directory Services and kills the server thread.
Parameters:
None. -  
Returns:
void

handleDialInvite

protected void handleDialInvite(InviteSignalEvent ise,
                                java.net.Socket so)
                         throws DesktopSignalingException,
                                cnrg.itx.datax.DataException
This method is used to handle an incoming call.
Parameters:
ise - is the InviteSignalEvent that contains all the necessary information about the peer
so - is the socket that should be used for communication.
Returns:
void
Throws:
DesktopSignalingException -  
See Also:
InviteSignalEvent

handleHangupInvite

protected void handleHangupInvite(HangupSignalEvent hse,
                                  java.net.Socket s)
This method is used to handle a hangup request.
Parameters:
hse - is the HangupSignalEvent that contains all the necessary information about the peer
s - is the socket that should be used for communication.
Returns:
void
See Also:
HangupSignalEvent

handleSendDTMFInvite

protected void handleSendDTMFInvite(DTMFSignalEvent dtmfse,
                                    java.net.Socket s)
This method is used to handle an incoming DTMF tone.
Parameters:
dtmfse - is the DTMFSignalEvent that contains all the necessary information about the peer
s - is the socket that should be used for communication.
Returns:
void
See Also:
DTMFSignalEvent

handleAliveInvite

protected void handleAliveInvite(AliveSignalEvent ase,
                                 java.net.Socket s)
This method is used to handle an alive request.
Parameters:
ase - is the AliveSignalEvent that contains all the necessary information about the peer
s - is the socket that should be used for communication.
Returns:
void
See Also:
AliveSignalEvent

handlePeerNotAlive

protected void handlePeerNotAlive(SignalConnection sc)
This method is used to clear up resources if the peer application is no longer active.
Parameters:
sc - is the SignalConnection that needs to be closed and removed
Returns:
void
See Also:
cnrg.itx.signal.client.SignalConnection

setServerPort

protected void setServerPort(int p)
The DesktopSignalingServer thread uses this method to register its port with DesktopSignaling.
Parameters:
p - is the port the Server thread is listening for requests.

tryDialSequence

protected DesktopSignaling.Result tryDialSequence(cnrg.itx.ds.UserID destUID,
                                                  cnrg.itx.ds.Location destAdd,
                                                  cnrg.itx.datax.Connection ac)
                                           throws ConnectException
This method performs a Dial Sequence including the 3-way handshake. The result of the hadnshake is returned to the callee method.

sendNewPacket

protected java.net.Socket sendNewPacket(SigPacket send,
                                        java.lang.String ip,
                                        int p)
                                 throws ConnectException
This method sends a packet over a TCP connection. A new socket is created.
Parameters:
send - is the SigPacket to send to the peer application
ip - is the String representation of the IP address of the destination
p - is the port of the destination application
Returns:
Socket that was created and used to send the packet
Throws:
DesktopSignalingException -  

sendPacket

protected void sendPacket(SigPacket send,
                          java.net.Socket sock)
                   throws ConnectException
This method sends a packet over an TCP socket. No new socket is created.
Parameters:
send - is the SigPacket to send to the peer application
sock - is the existing socket to use.
Returns:
void
Throws:
DesktopSignalingException -  

waitForPacket

protected SigPacket waitForPacket(java.net.Socket sock)
                           throws java.io.InterruptedIOException
This method waits for a packet on a given TCP socket. The wait times out after the specified number of seconds (in DesktopSignaling.TIMEOUT) have passed.
Parameters:
sock - is the existing socket to wait on
Returns:
SigPacket that is received
Throws:
java.io.InterruptedIOException -  

Register

protected void Register()
                 throws cnrg.itx.ds.DirectoryServiceException
This method registers the DesktopSignaling Component with DirectoryService.
Parameters:
None. -  
Returns:
Void.

unRegister

protected int unRegister()
This method Unregisters the DesktopSignaling Component on DirectoryService.
Parameters:
None. -  
Returns:
integer indicating whether the unregistration succeeded 1 - successfully unregistered -1 - unregister failed