javax.microedition.sip
Interface SipConnectionNotifier

public interface SipConnectionNotifier

This interface defines a SIP server connection notifier. The SIP server connection is opened with Connector.open()using a SIP URI string with the host and user omitted. For the detailed specification of SIP server URIs see the section: "SipConnection: Opening new server connection".

For example, URI sip:5060 defines an inbound SIP server connection on port 5060. The local address can be discovered using the getLocalAddress() method. If the port number is already reserved the Connector.open() MUST throw IOException.

SipConnectionNotifier can be also opened with sips: protocol scheme, which indicates that this server connection accepts only requests over secure transport (as defined in RFC 3261 [1] for SIPS URIs).

SipConnectionNotifier is queueing received messages. In order to receive incoming requests application calls the acceptAndOpen() method, which returns a SipServerConnection instance. If there are no messages in the queue acceptAndOpen() will block until a new request is received. If there are messages in the queue the implementation SHOULD send NotifyRequest() for each message when the new listener is assigned. SipServerConnection holds the incoming SIP request message. SipServerConnection is used to initialize and send responses.

Access to SIP server connections may be restricted by the security policy of the device. Connector.open MUST check access for the initial SIP server connection and acceptAndOpen() MUST check before returning each new SipServerConnection.

A SIP server connection can be used to dynamically select an available port by omitting both the host and the port parameters in the connection SIP URI string. The string sip: defines an inbound SIP server connection on a port which is allocated by the system. To discover the assigned port number use the getLocalPort() method.

The SipConnectionNotifier offers also an asynchronous callback interface to wait for incoming requests. The interface is defined in SipServerConnectionListener , which the user has to implement in order to receive notifications about incoming requests.

Here is an example method, which opens an inbound SIP server connection:

 public SipServerConnection openSipServerConnection() {
    SipConnectionNotifier scn = null;
    SipServerConnection ssc = null;
    
    try {
       // let the system select the port
       scn = (SipConnectionNotifier) Connector.open("sip:"); 
       ssc = scn.acceptAndOpen();
       return(ssc);
    } catch(Exception ex) {
      // handle IOException, InterruptedIOException, SecurityException
      // or SipException
    }
 }
 

Here is another example class, which uses the callback listener interface:

 public class SipServer implements SipServerConnectionListener {
    SipServer(String uri) {
       try {
          // user selects the port
          scn = (SipConnectionNotifier) Connector.open("sip:5080"); 
          scn.setListener(this); 
       } catch(Exception ex) {
          // handle Exceptions
       }
    }
    
    public void notifyRequest(SipConnectionNotifier scn) {
       SipServerConnection ssc = scn.acceptAndOpen();
       String method = ssc.getMethod();
       // continue with the incoming request etc...
    }
 }
 

See Also:

SipConnection, SipServerConnection, SipClientConnection, SipServerConnectionListener

Method Summary

SipServerConnection	acceptAndOpen() Accepts and opens a new SipServerConnection in this listening point.
java.lang.String	getLocalAddress() Gets the local IP address for this SIP connection.
int	getLocalPort() Gets the local port for this SIP connection.
void	setListener(SipServerConnectionListener sscl) Sets a listener for incoming SIP requests.

Method Detail

acceptAndOpen

SipServerConnection acceptAndOpen()
                                  throws java.io.IOException,
                                         SipException

Accepts and opens a new SipServerConnection in this listening point. If there are no messages in the queue the method will block until a new request is received.

Returns:

SipServerConnection which carries the received request

Throws:

java.io.IOException - if the connection can not be established or the SipConnectionNotifier is closed.

SipException - TRANSACTION_UNAVAILABLE if the system can not open new SIP transactions.

java.lang.SecurityException - if the caller does not have the required permissions to create server connections.

setListener

void setListener(SipServerConnectionListener sscl)
                 throws java.io.IOException

Sets a listener for incoming SIP requests. If a listener is already set it will be overwritten. Setting listener to null will remove the current listener.

Throws:

java.io.IOException - if the connection was closed

See Also:

SipServerConnectionListener, SipServerConnection

getLocalAddress

java.lang.String getLocalAddress()
                                 throws java.io.IOException

Gets the local IP address for this SIP connection.

Returns:

local IP address. Returns null if the address is not available.

Throws:

java.io.IOException - if the connection was closed

getLocalPort

int getLocalPort()
                 throws java.io.IOException

Gets the local port for this SIP connection.

Returns:

local port number, that the notifier is listening to. Returns 0 if the port is not available.

Throws:

java.io.IOException - if the connection was closed