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:

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

The SipDialog (client side) has following state diagram:

Dialog State Diagram Client

The SipDialog (server side) has following state diagram:

Dialog State Diagram Server

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)"sip:");
           scc = (SipClientConnection)
           scc.initRequest("SUBSCRIBE", scn);
           scc.setHeader("From", "");
           scc.setHeader("Accept", "application/pidf+xml");
           scc.setHeader("Event", "presence");
           scc.setHeader("Expires", "950");
           String contact = new String("sip:user@"+scn.getLocalAddress()
           scc.setHeader("Contact", contact);
           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");
           } 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)) {
           }else { 
               // send 481 "Subscription does not exist"
        } catch(Exception ex) { 
            // handle Exceptions 

See Also:

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


static final byte EARLY
See Also:
Constant Field Values


static final byte CONFIRMED
See Also:
Constant Field Values


static final byte TERMINATED
See Also:
Constant Field Values
Method Detail


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] Generating the Request, p.73):








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.

SipClientConnection with preset method and headers.
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.


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.

sc - SipConnection to be checked, can be either SipClientConnection or SipServerConnection
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.
java.lang.NullPointerException - if sc is null


byte getState()

Returns the state of the SIP Dialog.

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


java.lang.String getDialogID()

Returns the ID of the SIP Dialog.

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

Copyright © 2007 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.