Overview  Package   Class  Use  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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:

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

CONFIRMED

static final byte CONFIRMED
See Also:
Constant Field Values

EARLY

static final byte EARLY
See Also:
Constant Field Values

TERMINATED

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

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.

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.

getState

byte getState()

Returns the state of the SIP Dialog.

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

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
Overview  Package   Class  Use  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2002-2010 Nokia. All Rights Reserved.