javax.microedition.sip
Interface SipServerConnection

All Superinterfaces:

javax.microedition.io.Connection, SipConnection

public interface SipServerConnection

extends SipConnection

SipServerConnection represents 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 accessible in each 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 I/O methods above will throw IOException

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

• Can be called in every state
  getHeader
getHeaders
getRequestURI
getMethod
getStatusCode
getReasonPhrase
getDialog
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 establised 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, setHeader

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

initResponse

public 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 information is 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
 

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

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.

setReasonPhrase

public void setReasonPhrase(java.lang.String phrase)
                     throws SipException,
                            java.lang.IllegalArgumentException

Changes the default reason phrase.

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.