javax.microedition.sip
Interface SipServerConnection

All Superinterfaces:

javax.microedition.io.Connection, SipConnection

public interface SipServerConnection
extends SipConnection

SipServerConnection represents a SIP server transaction. SipServerConnection is created by the SipConnectionNotifier when a new request is received.

The SipServerConnection has following state diagram:

• Created, SipServerConnection created.
• Request Received, SipServerConnection returned from SipConnectionNotifier (not ACK). or provisional response(s) (1xx) sent.
• Initialized, response initialized calling initResponse()
• Stream Open, OutputStream opened with openContentOutputStream(). Opening InputStream for received request does not trigger state transition.
• Completed, transaction completed with sending final response (2xx, 3xx, 4xx, 5xx, 6xx) or resent 2xx or SipServerConnection for ACK returned from SipConnectionNotifier
• Terminated, the final state, in which the SIP connection has been terminated by error or closed

Note: The state diagram of SipServerConnection differs from the state diagram of SIP server transaction, which can be found in RFC 3261 [1] p.136-140

Following methods are restricted to certain states. The table below shows the list of methods available per state.

• Request Received
  • initResponse
  • openContentInputStream
• Initialized
  • addHeader
  • setHeader
  • removeHeader
  • setReasonPhrase
  • openContentOutputStream
  • send
• Stream Open
  • Methods in OutputStream and SipConnection.send
• Completed
  • send // only for resending 2xx responses
  • All get-methods, see below
• Terminated
  • The transaction and this connection is closed. The methods above throw SipException.INVALID_STATE if that is specified to the method and IOException for those methods (e.g. methods of Input/OutputStream) that does not have SipException specified. Methods that don't throw checked exceptions return without any action or return null as appropriate.

Following methods can be called in every state. The functionality is defined by the method depending on the information availability.

• Can be called in every state (with the exception of setErrorListener). Accessors return null in the Terminated state.
  • getHeader
  • getHeaders
  • getRequestURI
  • getMethod
  • getStatusCode
  • getReasonPhrase
  • getDialog
  • setErrorListener // can not be called in Terminated state
  • close // causes state transition to Terminated state

Error response for INVITE

If an error response is sent to the INVITE request, the client transaction layer will generate the ACK automatically on behalf of the transaction user (TU). Now when this ACK arrives on the server it is not passed up to TU as a new SipServerConnection. See RFC 3261 [1] p.136 "Figure 7: INVITE server transaction".

Resending 2xx for INVITE

If the ACK is not received for the final 2xx response, it is up to the TU (UA core) to resend 2xx response. In order to resend the 2xx response the SipServerConnection.send() can be called also in Completed state. See RFC 3261 [1] p.124 "17 Transactions" and p.135 "17.2.1 INVITE Server Transaction".

Code Examples

Following code example illustrates the usage of SIP server connection: opening, receiving one request (MESSAGE) and sending response:

 public receiveMessage() {
    SipConnectionNotifier scn = null;
    SipServerConnection ssc = null;
    String method = null;
   
    try {
       // Open SIP server connection and listen to port 5060
       scn = (SipConnectionNotifier) Connector.open("sip:5060");
      
       // block and wait for incoming request.
       // SipServerConnection is established and returned
       // when new request is received.
       ssc = scn.acceptAndOpen();

      // what was the SIP method
      method = ssc.getMethod();
      if(method.equals("MESSAGE")) {
         // read the content of the MESSAGE
         String contentType = ssc.getHeader("Content-Type");
         if((contentType != null) && contentType.equals("text/plain")) {
            InputStream is = ssc.openContentInputStream();
            int ch;
            // read content
            while ((ch = is.read()) != -1) {
             ...
            }
         }
         // initialize SIP 200 OK and send it back
         ssc.initResponse(200);
         ssc.send();
         ssc.close();
      }
    } catch(Exception ex) {
     // handle IOException, InterruptedIOException, SecurityException
     // or SipException
    }
 }
 

See Also:

SipConnectionNotifier, SipServerConnectionListener, SipClientConnection

Method Summary

void	initResponse(int code) Initializes SipServerConnection with a specific SIP response to the received request.
void	setReasonPhrase(java.lang.String phrase) Changes the default reason phrase.

Methods inherited from interface javax.microedition.sip.SipConnection

addHeader, getDialog, getHeader, getHeaders, getMethod, getReasonPhrase, getRequestURI, getStatusCode, openContentInputStream, openContentOutputStream, removeHeader, send, setErrorListener, setHeader

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

initResponse

void initResponse(int code)
                  throws java.lang.IllegalArgumentException,
                         SipException

Initializes SipServerConnection with a specific SIP response to the received request. The default headers and reason phrase will be initialized automatically. After this the SipServerConnection is in Initialized state. The response can be sent.

The procedure of generating the response and header fields is defined in RFC 3261 [1] p. 49-50. At least following headers are set by the method:

    From     // MUST equal the From header field of the request
    Call-ID  // MUST equal the Call-ID header field of the request
    CSeq     // MUST equal the CSeq field of the request
    Via      // MUST equal the Via header field values in the request 
                and MUST maintain the same ordering
    To       // MUST Copy if exists in the original request, 
                'tag' MUST be added if not present
    Contact  // If the server connection is in shared mode then the 
                value is set by the system for REGISTER, INVITE, 
                SUBSCRIBE and REFER. The value will be set according 
                to the terminal IP settings and the connection's 
                properties. If the connection is in the dedicated 
                mode then the user part is set to some default value 
                (e.g. 'user') which should be overwritten by the 
                application. 
                Example (dedicated mode),
                  Contact: sip:user@172.21.55.69:5060
                Example (shared mode),
                  Contact: "Mr X" <sip:mrx@172.21.55.69:5060>
 

These headers will be set on behalf of the user by the implementation the latest when sending the response. It implies that the header values may not be available for reading right after the initResponse 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.

See RFC 3261, page 162: Table 2: Summary of header fields, and RFC 3265, 7.1 for header field usage in the SUBSCRIBE and NOTIFY methods, and also RFC 3515, 2.2 for header field usage in the REFER method.

The following rules also apply:

If the system has automatically sent the "100 Trying" response, the 100 response initialized and sent by the user is just ignored.

If the system has automatically sent a response to a MESSAGE request then this method will throw SipException.ALREADY_RESPONDED. Systems that implement the message relay functionality (see RFC3428 - Session Initiation Protocol (SIP) Extension for Instant Messaging) inside the terminal may have definitive knowledge that the terminal has already responded with response code 202.

Parameters:

code - Response status code 1xx - 6xx

Throws:

java.lang.IllegalArgumentException - if the status code is out of range 100-699 (RFC 3261 p.28-29)

SipException - INVALID_STATE if the response can not be initialized, because of wrong state. ALREADY_RESPONDED if the system has already sent a response to a MESSAGE request.

setReasonPhrase

void setReasonPhrase(java.lang.String phrase)
                     throws SipException

Changes the default reason phrase.

Parameters:

phrase - the reason phrase to be set. Empty string or null means that an empty (zero-length) reason phrase will be set.

Throws:

java.lang.IllegalArgumentException - if the reason phrase is illegal.

SipException - INVALID_STATE if the response can not be initialized, because of wrong state. INVALID_OPERATION if the reason phrase can not be set.