Package cnrg.itx.signal

Provides the control layer for internet telephony.

See:
          Description

Interface Summary
ErrorResponse This interface contains all the SIP error status codes.
InfoResponse This interface contains non-error SIP status codes.
SignalConnectionObserver This interface defines the methods that applications need to implement in order to use the non-blocking dial functionality.
SignalID This interface contains all the Signaling Codes for deciphering methods, packet types and results.
SignalingObserver This interface defines the methods that applications need to implement in order to use Signaling services.
 

Class Summary
AbstractSignalingObserver This class provides default implementations for the methods defined in the SignalingObsrver interface.
DesktopSignaling The primary Signaling Object that allows the application to access all telephony services.
InvitePacket This class extends SigPacket and is used in the 3-way handshake during a Dial Sequence.
Little  
SignalConnection This class contains vital signaling information to identify and hangup peer applications.
SigPacket This is the base class representing the Signaling Packet that is sent to and from all Signaling components.
SIPInterface This class converts methods in InvitePacket into SIP packet format and vice versa.
 

Exception Summary
ConnectException This class forms the base class for all Connection related exceptions thrown by DesktopSignaling components.
ConnectFailedToOpenSocketException This class represents an exception thrown by DesktopSignaling if a socket connection could not be made with a peer component.
ConnectNullObjectSentException This class represents an exception thrown by DesktopSignaling if a null SigPacket is being sent to a peer component.
ConnectNullSocketException This class represents an exception thrown by DesktopSignaling if a null Socket is used to communicate with a peer component.
DesktopSignalingException This class represents the base exception class thrown by DesktopSignaling.
InviteBusyException This class represents an exception thrown if the peer is busy.
InviteException This class forms the base class for all Invite related exceptions thrown by DesktopSignaling during the dial sequence.
InviteIncompatibleException This class represents an exception thrown if the peer application is not compatible .
InviteInvalidException This class represents an exception thrown if the peer application is invalid.
InviteRejectException This class represents an exception thrown if the peer rejects the call.
InviteTimeoutException This class represents an exception thrown if the peer application does not respond.
SIPException SIPException is thrown when there is an error in implementing the SIP protocol.
 

Package cnrg.itx.signal Description

Provides the control layer for internet telephony.   Signaling hides all the complexity of finding the user (Directory Service), querying the user if he or she wants to talk to the caller and setting up a mutually acceptable channel to allow the call to take place (Data Exchange). The application can Dial a user by simply passing in a userid in String format or a telephone number to Dial.  If a telephone number is provided then Signaling forwards the request to the Gateway (as if it is a call to another PC) and returns a SignalConnection (once the Dial Sequence with Gateway is complete).

In order to use signaling capabilities, the application must implement the cnrg.itx.signal.SignalingObserver interface. For control over the dial sequence the application must in addition implement the cnrg.itx.signal.SignalConnectionObserver interface. These interfaces list possible events that require application feedback in order to be handled.

How applications can use the Non-blocking Dial

1) Implement all the methods in the cnrg.itx.signal.SignalConnectionObserver interface.   This allows the DialThread making the call to inform the application about the result(s) of the dial sequence.

2) Once these methods are implemented the application can do the following to use the non-blocking Dial():

	DesktopSignaling myDS; //handle to a instantiated DesktopSignaling
	String uid = "userIDorPhone";
	LocationList ll = myDS.getLocationList(uid);
	
	//The location list contains all the possible places for the given uid.  Any of these locations
	//may be used to get the desired location.  See cnrg.itx.ds.LocationList for more information.
	Location destLoc = ll.first();
	
	//The Dial function returns a SignalConnection immediately, which contains a DialThread object
	SignalConnection mySC = myDS.Dial(uid, destLoc, (SignalConnectionObserver) this);
	
	//This actually starts the DialThread and begins the Dial sequence.  The Dial thread will 
	//generate an event by using the appropriate method in SignalConnectionObserver.
	mySC.startCall();

The function can return after calling startCall(). Now, if the application wants to abort the call, it can simply say, mySC.abortCall(). If the call is still being made the thread stops mid-way and exits cleanly.

3) An example of what the DialThread does follows:

The DialThread will conduct a 3-way handshake with the peer application at the specified location (in destLoc from the above application). After the Dial Sequence the thread will call one of the following methods on the application:

onAccept(), onReject(), onBusy(), onInvalid(), onTimeout(), onIncompatible(), or onError()

These events describe what happened in the dial attempt and pass in a DialSignalEvent object to the application (or a DesktopSignalingException object in the case of onError()). The application should use the information contained in this extension of SignalEvent. For example, onAccept() & onReject() may be implemented as follows:

	public void onAccept(DialSignalEvent dse){
		SignalConnection sc = dse.getSignalConnection();
		sc.open();//open connection for data transfer
		//inform the user that he or she may start talking
	}

	public void onReject(DialSignalEvent dse){
		String reason = dse.getReason();
		//Tell the user why the call was rejected, in the status bar.
		//The SignalConnection is closed by Signaling before this method is called.
	}