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).

Three SIP requests can open a dialog: INVITE, SUBSCRIBE/NOTIFY and REFER/NOTIFY. An implementation compliant to this specification must support all of the following ways of creating dialogs:

• 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 are no other subscriptions alive in this dialog. For more information please refer to RFC 3265 [2], Chapter 3.3.4.
• REFER-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 are no other subscriptions alive in this dialog. For more information please refer to RFC 3515 [6].

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:UserB@host.com");
           scc.initRequest("SUBSCRIBE", scn);
           scc.setHeader("From", "sip:UserA@host.com");
           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

static final byte EARLY

See Also:

Constant Field Values

CONFIRMED

static final byte CONFIRMED

See Also:

Constant Field Values

TERMINATED

static final byte TERMINATED

See Also:

Constant Field Values

Method Detail

getNewClientConnection

SipClientConnection getNewClientConnection(java.lang.String method)
                                           throws 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

These headers will be set on behalf of the user by the implementation the latest when sending the request. It implies that the header values may not be available for reading right after the getNewClientConnection method returns. The user may also set (overwrite) these headers, in this case the values set by the user take precedence over the values set by the implementation.

There may be scenarios when it is not possible to create new SipClientConnection objects from the dialog. In this case the implementation of this specification MAY throw SipException.TRANSACTION_UNAVAILABLE.

Returns:

SipClientConnection with preset method and headers.

Throws:

java.lang.IllegalArgumentException - if the method is invalid

java.lang.NullPointerException - if method name is null

SipException - INVALID_STATE if the new connection can not be established in the current state of dialog. TRANSACTION_UNAVAILABLE if the creation of the SipClientConnection object is not possible for any reason.

isSameDialog

boolean isSameDialog(SipConnection sc)

Does the given SipConnection belong to this dialog. Note that two SipDialog objects that are created from connections belonging to the same dialog may not be the same Java object. But the following statements are true: they have the same dialog ID and the same requests can be created from them.

Parameters:

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

Returns:

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

Throws:

java.lang.NullPointerException - if sc is null

getState

byte getState()

Returns the state of the SIP Dialog.

Returns:

dialog state. One of the state constant defined in this interface.

getDialogID

java.lang.String getDialogID()

Returns the ID of the SIP Dialog.

Returns:

Dialog ID. Refer to RFC 3261 page 69 for the exact format of the dialog ID. Returns null if the dialog is terminated.