javax.microedition.sip
Class SipRefreshHelper

java.lang.Object
  javax.microedition.sip.SipRefreshHelper

public class SipRefreshHelper

extends java.lang.Object

This class implements the functionality that facilitates the handling of refreshing requests on behalf of the application. Some SIP requests (REGISTER, SUBSCRIBE, ...) need to be timely refreshed (binding between end point and server, see RFC 3261 - chapter 10.2.1 page 58). For example the REGISTER request (RFC 3261, chapter 10 page 56) needs to be re-sent to ensure that the originating end point is still well and alive. The request's validity is proposed by the end point in the request and confirmed in the response by the registrar/notifier for example in expires header (RFC 3261, chapter 2 page 5). The handling of such binding would significantly increase application complexity and size. As a consequence the SipRefreshHelper can be used to facilitate such operations. When the application wants to send a refreshable request it:

• implements SipRefreshListener callback interface.
• creates a new SipClientConnection and sets it up.
• calls the method enableRefresh(SipRefreshListener). A refresh ID is returned. If the request is not refreshable the method returns 0.
• if the refresh task fails a failure event is sent to the SipRefreshListener

A reference to the SipRefreshHelper object is obtained by calling the static method SipRefreshHelper.getInstance() (singleton pattern).

Finally, using the refresh ID returned from enableRefresh(SipRefreshListener) the application can:

• stop() a refresh. The possible binding between end point and server is cancelled (RFC3261, chapter 10.2.2 page 61).
• update(...) the refreshed request with new parameters (Contact info and new payload). Note that this functionality is limited to the most typical case. A more complex case would require to stop the refresh and to create a new request with the needed updates.

When all refresh tasks belonging to one refresh listener are stopped, the listener reference will be removed from the SipRefreshHelper.

Code example where REGISTER is sent, updated and finally stopped:

 class SipRefreshExample implements SipClientConnectionListener,
  SipRefreshListener { 

    int refreshID = 0; 
    int refreshStatus = 0; 
    SipRefreshHelper refHelper = null;

    public void sendRegister() { 
        SipClientConnection sc = null; 
        try { 
           // Initialize connection to the registrar host.com
           sc = (SipClientConnection)
	         Connector.open("sip:host.com");
           sc.setListener(this);
           // Initialize request and set From, To and Contact headers
           sc.initRequest("REGISTER", null); 
           sc.setHeader("From", "sip:[email protected]"); 
           sc.setHeader("To", "sip:[email protected]"); 
           sc.setHeader("Contact", "<sip:[email protected]>;expires=3600"); 
           sc.setHeader("Contact", "<mailto:[email protected]>;expires=4294967295"); 
           refreshID = sc.enableRefresh(this); 
           sc.send(); 
           refHelper = SipRefreshHelper.getInstance(); 
           //-----------------------------
           // do something else for a while
           //------------------------------
           // update REGISTER, with new "mailto:" Contact and no content
           if(refreshStatus == 200) { // check that refresh was successful
               String c[] = { "<mailto:[email protected]>" };
               refHelper.update(refreshID, c, null, 0, 6000);
           }
           //-----------------------------
           // do something else for a while
           //------------------------------
           // stop REGISTER refresh altogether
           if(refreshStatus == 200) { // check that refresh is still ok
               refHelper.stop(refreshID);
           }
        } catch(Exception ex) { // handle Exceptions 
        } 
    } 

    public void notifyResponse(SipClientConnection scc) { 
        try { 
           // retrieve the response received 
           scc.receive(0); 
           if(scc.getStatusCode() == 200) { 
              // handle 200 OK response
           }else { 
              // handle possible error responses
           }
        } catch(Exception ex) { 
            // handle Exceptions 
        } 
    } 

    public void refreshEvent(int ID, int statusCode, String reasonPhrase) { 
       refreshStatus = statusCode;
       if (statusCode == 0){ 
                // stopped refresh 
       }else if (statusCode == 200){ 
                // successful refresh
       }else { 
                // failed request 
       } 
    }
 } 

See Also:

SipClientConnection.enableRefresh(SipRefreshListener)

Method Summary

static SipRefreshHelper	getInstance() Returns the instance of SipRefreshHelper
void	stop(int refreshID) Stop refreshing a specific request related to refeshID.
java.io.OutputStream	update(int refreshID, java.lang.String[] contact, java.lang.String type, int length, int expires) Updates one refreshed request with new values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static SipRefreshHelper getInstance()

Returns the instance of SipRefreshHelper

Returns:

the instance of SipRefreshHelper singleton

stop

public void stop(int refreshID)

Stop refreshing a specific request related to refeshID. The possible binding between end point and registrar/notifier is cancelled (RFC3261, chapter 10.2.2 page 61). An event will be sent to the listeners with refreshID and statusCode = 0 and reasonPhrase = "refresh stopped".

Parameters:

refreshID - the ID of the refresh to be stopped. If the ID does not match any refresh task the method does nothing.

update

public java.io.OutputStream update(int refreshID,
                                   java.lang.String[] contact,
                                   java.lang.String type,
                                   int length,
                                   int expires)

Updates one refreshed request with new values.

• new Contact header values. existing values are kept if this is null.
  
• Expires header value. expires = 0 has the same effect as calling stop(refreshID). expires = -1 leaves the Expires header out.
  
• new payload: Content-Type and Content-Length. The message is sent when the returned OutputStream is closed. If no content is set the message will be sent automatically and the method returns null.

Parameters:

refreshID - ID returned from enableRefresh(...). If the ID does not match any refresh task the method just returns without doing anything.

contact - new Contact headers as String array. Replaces all old values. Multiple Contact header values are applicable only for REGISTER method. If contact param is null or empty the system will set the Contact header.

type - value of Content-Type (null or empty, no content)

length - value of Content-Length (<=0, no content)

expires - value of Expires (-1, no Expires header), (0, stop the refresh)

Returns:

Returns the OutputStream to fill the content. If the update does not have new content (type = null and/or length = 0) method returns null and the message is sent automatically.

Throws:

java.lang.IllegalArgumentException - if some input parameter is invalid