overview-summary.html

sipapi 说明文档.用于JAVA的SIP开发及应用.

    <h3>How to use the SIP API for J2ME</h3>
    The SIP API is used by the applications to implement SIP User Agent (UA)
    functionality. The following picture shows what interfaces terminals 
    A and B are using to implement SIP User Agent Client (UAC) and 
    User Agent Server (UAS) functionality respectively. 
    See <A HREF="#SIP_GLOSSARY">Glossary</A> for explanation of UAC and UAS functionality.
    <br>
    <img src="./doc-files/jsr180-API-usage-1.gif" width=80% height=80%>
    <br>
    In reality applications will use both SIP client and server
    connections in the same terminal (terminal A in picture below) and thus
    implementing both UAC and UAS functionality.
    <br>
    <img src="./doc-files/jsr180-API-usage-2.gif" width=80% height=80%>
    <br>
    The following code examples shows how to open SIP connections and the usage
    of the main classes <code>SipClientConnection</code>, 
    <code>SipServerConnection</code> and <code>SipConnectionNotifier</code>. 
    Examples of helper classes: <code>SipDialog</code>, 
    <code>SipAddress</code>, <code>SipHeader</code> and 
    <code>RefreshHelper</code> are shown in the API documentation.
    <p>
    The example below shows how to open a SIP client connection,
    send one request and receive a response. The interface used in this
    simple client connection example is <code>SipClientConnection</code>.
	<p></p>
    <pre>
 public void sendTextMessage(String msg) {
    SipClientConnection sc = null;
    try {
       // open SIP connection
       sc = (SipClientConnection) Connector.
	                      open("sip:[e-mail]:5060");
       
       // initialize SIP request MESSAGE
       sc.initRequest("MESSAGE", null);
       
       // set some headers
       sc.setHeader("From", "sip:[e-mail]");
       sc.setHeader("Subject", "testing...");

       // write message body
       sc.setHeader("Content-Type", "text/plain");
       sc.setHeader("Content-Length", Integer.toString(msg.length()));
       OutputStream os = sc.openContentOutputStream();
       os.write(msg.getBytes());
       os.close(); // close stream and send the message to the network

       // wait max 15 seconds for response
       sc.receive(15000);

       // response received
       if(sc.getStatusCode() == 200) {
          // handle 200 OK response
       } else {
          // handle other responses
       }
       sc.close();    
     } catch(Exception ex)
       // handle Exceptions
     } 
 }
   </pre>
   The following code example shows how to open a SIP server connection,
   receive one request and send a response. The interfaces used in the
   simple server connection example are <code>SipConnectionNotifier</code>
   and <code>SipServerConnection</code>.
   <p></p>
   <pre>
 public receiveMessage() {
    SipConnectionNotifier scn = null;
    SipServerConnection ssc = null;
    String method = null;
    
    try {
       // Open SIP server connection and listen to incoming requests
       scn = (SipConnectionNotifier) Connector.open("sip:");
       
       // block and wait for incoming request.
       // SipServerConnection is established and returned
       // when a 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
    }
 }
   </pre>
   

    <h3>SIP (Session Initiation Protocol) Overview</h3>
    <p>
    SIP is an application-layer control protocol that can establish,
   modify, and terminate multimedia sessions. SIP can also invite 
   participants to already existing sessions. SIP transparently supports 
   name mapping and redirection services, which supports personal mobility 
   - users can maintain a single externally visible identifier regardless 
   of their network location (see RFC 3261 [1]). SIP can also be used to implement
   non-real-time services like Instant Messaging and Presence [2][3].
   </p>
   <p>
   SIP supports five facets of establishing and terminating multimedia
   communications:
   </p>
   <dl>
   <dt>User location
   <dd>- determination of the end system to be used for communication
   <dt>User availability
   <dd>- determination of the willingness of the called
       party to engage in communications
   <dt>User capabilities
   <dd>- determination of the media and media parameters to be used
   <dt>Session setup
   <dd>- establishment of session parameters at
           both called and calling party
   <dt>Session management
   <dd>- including transfer and termination of
           sessions, modifying session parameters, and invoking services
   </dl> 
    <p>

  <h3><A NAME="SIP_GLOSSARY">Glossary</A></h3>

  This section defines some terms used in the specification. Please also refer to the RFC 3261 [1].

  <table border="1">
  <tr>
     <td valign="top">
        <p>Client Connection</p>
      </td>
      <td>
        <p>The SIP API's client connection 
	(class <code>SipClientConnection</code>) is an interface to 
	SIP client transaction, which sends original request and
	receives responses until final response. See also, <em>SIP Transaction</em> 
	and <em>Server Connection</em>.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>Server Connection</p>
      </td>
      <td>
        <p>The SIP API's  server connection 
	(class <code>SipServerConnection</code>) is an interface to 
	SIP server transaction, which receives the original request and
	sends response(s) until final response. Also see, <em>SIP Transaction</em> and
	<em>Client Connection</em>.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>SIP Transaction</p>
      </td>
      <td>
        <p>A SIP transaction occurs between a client and a
         server and comprises all messages from the first request sent
         from the client to the server up to a final (non-1xx) response
	 sent from the server to the client.  If the request is INVITE
         and the final response is a non-2xx, the transaction also
         includes an ACK to the response.  The ACK for a 2xx response to
         an INVITE request is a separate transaction.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>SIP Dialog</p>
      </td>
      <td>
        <p>The SIP API's class <code>SipDialog</code>
	 keeps the information about one SIP dialog. Using that interface
	 the user is able to send subsequent requests within that dialog.
	 A dialog is a peer-to-peer SIP relationship between two
         UAs that persists for some time.  A dialog is established by
         SIP messages, such as a 2xx response to an INVITE request.  A
         dialog is identified by a call identifier, local tag, and a
         remote tag.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>User Agent (UA)</p>
      </td>
      <td>
        <p>A logical entity that can act as both a user
         agent client and user agent server. Typically an application
	 (e.g. MIDlet) will implement the User Agent functionality
	 using the SIP API for J2ME. See also, <em>UAC</em> and <em>UAS</em>.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>User Agent Client (UAC)</p>
      </td>
      <td>
        <p>A user agent client is a logical entity
         that creates a new request, and then uses the client
         transaction state machinery to send it.  The role of the UAC lasts
         only for the duration of that transaction.  In other words, if
         a piece of software initiates a request, it acts as a UAC for
         the duration of that transaction.  If it receives a request
         later, it assumes the role of a user agent server for the
         processing of that transaction.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>User Agent Server (UAS)</p>
      </td>
      <td>
        <p>A user agent server is a logical entity
         that generates a response to a SIP request.  The response
         accepts, rejects, or redirects the request.  This role lasts
         only for the duration of that transaction.  In other words, if
         a piece of software responds to a request, it acts as a UAS for
         the duration of that transaction.  If it generates a request
         later, it assumes the role of a user agent client for the
         processing of that transaction.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">
        <p>Method</p>
      </td>
      <td>
        <p>The method is the primary function that a request is meant
         to invoke on a server.  The method is carried in the request
         message itself.  Example methods are INVITE and BYE.
          </p>
      </td>
    </tr>
  <tr>
     <td valign="top">