sipinterface.java

基于MJSIP的j2me客户端

/*
 * Copyright (C) 2005 Luca Veltri - University of Parma - Italy
 * 
 * This file is part of MjSip (http://www.mjsip.org)
 * 
 * MjSip is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * MjSip is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with MjSip; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Author(s):
 * Luca Veltri ([e-mail])
 */

package org.zoolu.sip.provider;


import org.zoolu.sip.message.Message;


/** SipInterface is actually the SIP SAP (Service Access Point) and can be used to send
  * and receive SIP messages associated with a specific method, transaction, or dialog.
  * <p/>
  * SipInterface provides a simple interface to the multiplexing function provided
  * by the SipProvider layer.
  * <br/> It simply wraps the SipProvider by adding and removing the listener
  * for capturing received SIP messages.
  * <p/>
  * When creating a new SipInterface the following parameters, have to be specified:
  * <b> - <i>sip_provider<i/> is the SipProvider the SipInterface has to be bound to,
  * <b> - <i>id<i/> is the SIP interface identifier the SipInterface has to be bound to,
  * <b> - <i>listener<i/> is the SipInterfaceListener that received messages are passed to.
  * <p/>
  * The SIP interface <i>id<i/> specifies the type of messages the listener is going to
  * receive for. Together with the <i>sip_provider<i/>, it represents the complete SIP
  * Service Access Point (SAP) address/identifier used for demultiplexing SIP messages
  * at receiving side. 
  * <p/>
  * The identifier can be of one of the three following types: transaction_id, dialog_id,
  * or method_id. These types of identifiers characterize respectively:
  * <br> - messages within a specific transaction,
  * <br> - messages within a specific dialog,
  * <br> - messages related to a specific SIP method.
  * It is also possible to use the the identifier ANY to specify 
  * <br> - all messages that are out of any transactions, dialogs, or already specified
  *        method types.
  * <p>
  * When receiving a message, the underling SipProvider first tries to look for
  * a SipInterface associated to the corresponding transaction, then looks for
  * a SipInterface associated to the corresponding dialog, then for
  * a SipInterface associated to the corresponding method type, and finally for
  * a SipInterface associated to ANY messages.
  * If the present SipInterface id matches, the SipInterfaceListener method
  * <i>onReceivedMessage()</i> is fired.
  */
public class SipInterface implements SipProviderListener
{

   /** SipProvider */
   SipProvider sip_provider;  

   /** Identifier */
   Identifier id;  

   /** SipInterfaceListener */
   SipInterfaceListener listener;  
   

   // *************************** Costructors ***************************

   /** Creates a new SipInterface. */ 
   public SipInterface(SipProvider sip_provider, SipInterfaceListener listener)
   {  this.sip_provider=sip_provider;
      this.listener=listener;
      id=SipProvider.ANY;
      sip_provider.addSipProviderListener(id,this);
   }


   /** Creates a new SipInterface. */ 
   public SipInterface(SipProvider sip_provider, Identifier id, SipInterfaceListener listener)
   {  this.sip_provider=sip_provider;
      this.listener=listener;
      this.id=id;
      sip_provider.addSipProviderListener(id,this);
   }


   // ************************** Public methods *************************

   /** Close the SipInterface. */ 
   public void close()
   {  sip_provider.removeSipProviderListener(id);
   }


   /** Gets the SipProvider. */ 
   public SipProvider getSipProvider()
   {  return sip_provider;
   }


   /** Sends a Message, specifing the transport portocol, nexthop address and port.
     * <p> This is a low level method and
     * forces the message to be routed to a specific nexthop address, port and transport,
     * regardless whatever the Via, Route, or request-uri, address to. 
     * <p>
     * In case of connection-oriented transport, the connection is selected as follows:
     * <br> - if an existing connection is found matching the destination
     *        end point (socket), such connection is used, otherwise
     * <br> - a new connection is established
     *
     * @return It returns a Connection in case of connection-oriented delivery
     * (e.g. TCP) or null in case of connection-less delivery (e.g. UDP)
     */
   public ConnectionIdentifier sendMessage(Message msg, String proto, String dest_addr, int dest_port, int ttl)
   {  return sip_provider.sendMessage(msg,proto,dest_addr,dest_port,ttl); 
   }

   /** Sends the message <i>msg</i>.
     * <p>
     * The destination for the request is computed as follows:
     * <br> - if <i>outbound_addr</i> is set, <i>outbound_addr</i> and 
     *        <i>outbound_port</i> are used, otherwise
     * <br> - if message has Route header with lr option parameter (i.e. RFC3261 compliant),
     *        the first Route address is used, otherwise
     * <br> - the request's Request-URI is considered.
     * <p>
     * The destination for the response is computed based on the sent-by parameter in
     *     the Via header field (RFC3261 compliant)
     * <p>
     * As transport it is used the protocol specified in the 'via' header field 
     * <p>
     * In case of connection-oriented transport:
     * <br> - if an already established connection is found matching the destination
     *        end point (socket), such connection is used, otherwise
     * <br> - a new connection is established
     *
     * @return Returns a ConnectionIdentifier in case of connection-oriented delivery
     * (e.g. TCP) or null in case of connection-less delivery (e.g. UDP)
     */
   public ConnectionIdentifier sendMessage(Message msg)
   {  return sip_provider.sendMessage(msg); 
   }


   /** Sends the message <i>msg</i> using the specified connection. */
   public ConnectionIdentifier sendMessage(Message msg, ConnectionIdentifier conn_id)
   {  return sip_provider.sendMessage(msg,conn_id);
   }


   //************************* Callback methods *************************
   
   /** When a new Message is received by the SipProvider. */
   public void onReceivedMessage(SipProvider sip_provider, Message message)
   {  if (listener!=null) listener.onReceivedMessage(this,message);
   }

}