javax.microedition.sip
Interface SipDialog

public interface SipDialog

SipDialog represents one SIP Dialog. The SipDialog can be retrieved from a SipConnection object, when it is available (at earliest after provisional 101-199 response).

Basically, two SIP requests can open a dialog:

• INVITE-1xx-2xx-ACK will open a dialog. Subsequent SipClientConnection in the same dialog can be obtained by calling getNewClientConnection(String method) method. The dialog is terminated when the transaction BYE-200 OK is completed. For more information please refer to RFC 3261 [1], Chapter 12.
  
• SUBSCRIBE-200 OK(or matching NOTIFY) will open a dialog. Subsequent SipClientConnection in the same dialog can be obtained by calling getNewClientConnection(String method) method. The dialog is terminated when a notifier sends a NOTIFY request with a "Subscription-State" of "terminated" and there is no other subscriptions alive with this dialog. For more information please refer to RFC 3265 [2], Chapter 3.3.4.

SipDialog has following states (for both client and server side):

• Initialized, internal state where the dialog has been created. This state is not visible to the user, since the dialog can be fetched earliest in the Early state.
  
  
• Early, provisional 101-199 response received (or sent)

All methods available.


• Confirmed, final 2xx response received (or sent) for the original request. Or NOTIFY confirming the subscription received (or sent).

All methods available.


• Terminated, no response or error response (3xx-6xx) received (or sent). Also if the dialog is terminated with BYE or un-SUBSCRIBE.

Method getNewClientConnection() can not be called in this state.

The SipDialog (client side) has following state diagram:


The SipDialog (server side) has following state diagram:



Following code example shows a simple example of using SipDialog in conjunction with SipClientConnection and SipServerConnection. SipDialog is used to send subsequent SUBSCRIBE request as well as detecting if received NOTIFY belongs to the same dialog (i.e. subscription). Further dialog information like "Call-ID" or "remote tag" can be read from the subsequent SipClientConnection as demonstrated.

 class SipDialogExample implements SipServerConnectionListener { 

    SipDialog dialog;
    SipClientConnection scc;
    SipConnectionNotifier scn;
    String callID;
    String remoteTag;

    public void sendSubscribe() { 
        try { 
           scn = (SipConnectionNotifier) Connector.open("sip:");
           scn.setListener(this);
           scc = (SipClientConnection)
	         Connector.open("sip:[email protected]");
           scc.initRequest("SUBSCRIBE", scn);
           scc.setHeader("From", "sip:[email protected]");
           scc.setHeader("Accept", "application/pidf+xml");
           scc.setHeader("Event", "presence");
           scc.setHeader("Expires", "950");
           String contact = new String("sip:user@"+scn.getLocalAddress()+":"+scn.getLocalPort());
           scc.setHeader("Contact", contact);
           scc.send(); 
           boolean resp = scc.receive(10000); // wait 10 secs for response 
           if(resp) {
               if(scc.getStatusCode() == 200) {
                   dialog = scc.getDialog();
                   // initialize new SipClientConnection
                   scc = dialog.getNewClientConnection("SUBSCRIBE");
                   // read dialog Call-ID
                   callID = scc.getHeader("Call-ID");
                   // read remote tag
                   SipHeader sh = new SipHeader("To", scc.getHeader("To"));
                   remoteTag = sh.getParameter("tag");
                   // unSUBSCRIBE
                   scc.setHeader("Expires", "0");
                   scc.send();
               }
           } else {
               // didn't receive any response in given time
           }
        } catch(Exception ex) { 
            // handle Exceptions 
        } 
    } 

    public void notifyRequest(SipConnectionNotifier scn) { 
        try { 
           SipServerConnection ssc;
           // retrieve the request received 
           ssc = scn.acceptAndOpen();
           // check if the received request is NOTIFY and it belongs to our dialog
           if(ssc.getMethod().equals("NOTIFY") && dialog.isSameDialog(ssc)) {
               ssc.initResponse(200);
               ssc.send();
           }else { 
               // send 481 "Subscription does not exist"
               ssc.initResponse(481);
               ssc.send();
           }
        } catch(Exception ex) { 
            // handle Exceptions 
        } 
    }
 }
 

See Also:

SipConnection.getDialog()

Field Summary

static byte	CONFIRMED
static byte	EARLY
static byte	TERMINATED

Method Summary

java.lang.String	getDialogID() Returns the ID of the SIP Dialog.
SipClientConnection	getNewClientConnection(java.lang.String method) Returns a new SipClientConnection in this dialog.
byte	getState() Returns the state of the SIP Dialog.
boolean	isSameDialog(SipConnection sc) Does the given SipConnection belong to this dialog.

Field Detail

EARLY

public static final byte EARLY

See Also:

Constant Field Values

CONFIRMED

public static final byte CONFIRMED

See Also:

Constant Field Values

TERMINATED

public static final byte TERMINATED

See Also:

Constant Field Values

Method Detail

getNewClientConnection

public SipClientConnection getNewClientConnection(java.lang.String method)
                                           throws java.lang.IllegalArgumentException,
                                                  SipException

Returns a new SipClientConnection in this dialog. The returned SipClientConnection will be in Initialized state. The object is initialized with the given method and following headers will be set at least (for details see RFC 3261 [1] 12.2.1.1 Generating the Request, p.73):

    To           
    From         
    CSeq         
    Call-ID      
    Max-Forwards 
    Via          
    Contact      
    Route        // if the dialog route is not empty
 

Returns:

SipClientConnection with preset method and headers.

Throws:

java.lang.IllegalArgumentException - if the method is invalid

SipException - INVALID_STATE if the new connection can not be established in the current state of dialog.

isSameDialog

public boolean isSameDialog(SipConnection sc)

Does the given SipConnection belong to this dialog.

Parameters:

sc - SipConnection to be checked, can be either SipClientConnection or SipServerConnection

Returns:

true if the SipConnection belongs to the this dialog. Returns false if the connection is not part of this dialog or the dialog is terminated.

getState

public byte getState()

Returns the state of the SIP Dialog.

Returns:

dialog state byte number.

getDialogID

public java.lang.String getDialogID()

Returns the ID of the SIP Dialog.

Returns:

Dialog ID (Call-ID + remote tag + local tag). Returns null if the dialog is terminated.