sipstack.hxx

一个著名的SIP协议栈

#if !defined(RESIP_SIPSTACK_HXX)
#define RESIP_SIPSTACK_HXX

#include <set>
#include <iosfwd>

#include "rutil/TimeLimitFifo.hxx"
#include "rutil/Mutex.hxx"
#include "rutil/TransportType.hxx"
#include "rutil/BaseException.hxx"
#include "resip/stack/TransactionController.hxx"
#include "resip/stack/SecurityTypes.hxx"
#include "resip/stack/StatisticsManager.hxx"
#include "resip/stack/TuSelector.hxx"
#include "rutil/dns/DnsStub.hxx"

namespace resip 
{

class ApplicationMessage;
class Data;
class Message;
class Security;
class SipMessage;
class StatisticsManager;
class Tuple;
class Uri;
class TransactionUser;
class AsyncProcessHandler;
class Compression;

class SipStack
{
   public:
      /** 
          Constructor

          @param security   Security Object required by the stack for TLS, DTLS, SMIME
                            and Identity-draft compliance.  If 0 is passed in 
                            the stack will not support these advanced security 
                            features.  The compile flag USE_SSL is also required.
                            The security object will be owned by the SipStack and
                            deleted in the SipStack destructor.  Default is 0. 

          @param handler    AsyncProcessHandler that will be invoked when Messages 
                            are posted to the stack.  For example:  SelectInterruptor.
                            Default is 0.

          @param stateless  This parameter does not appear to be used.

          @param socketFunc [PLEASE FILL THIS IN]

          @param compression Compression configuration object required for
                             SigComp. If set to 0, then SigComp compression
                             will be disabled.
      */
      SipStack(Security* security=0, 
               const DnsStub::NameserverList& additional = DnsStub::EmptyNameserverList,
               AsyncProcessHandler* handler = 0, 
               bool stateless=false,
               AfterSocketCreationFuncPtr socketFunc = 0,
               Compression *compression = 0);      

      virtual ~SipStack();

      /** 
         Inform the transaction state machine processor that it should not
         create any new transactions and to perform an orderly shutdown. When
         the transactions are all terminated, return a ShutdownMessage to the TU
      */
      void shutdown();

      class Exception : public BaseException
      {
         public:
            Exception(const Data& msg, const Data& file, const int line)
               : BaseException(msg, file, line) {}

            const char* name() const { return "SipStack::Exception"; }
      };

      /** 
         Used by the application to add in a new built-in transport.  The transport is
         created and then added to the Transport Selector.

         @throws Transport::Exception If the transport couldn't be added, usually
                                      because the port was already bound.

         @param protocol              TCP, UDP, TLS, DTLS, etc.

         @param port                  Specifies which port to bind to.  See sipDomainname
                                      parameter for more info.

         @param version               Protocol Version:  V4 or V6

         @param ipInterface           Specifies which ethernet interface to bind to. If set to 
                                      Data::Empty, bind to all interfaces.

         @param sipDomainname         For TLS only, if port = 0, use DNS to lookup the port number 
                                      for the specified domain. Only allow messages to 
                                      be sent as the specified domain.  For default case, 
                                      you can pass in domainname = DnsUtil::getLocalDomainName().

         @param privateKeyPassPhrase  Private key pass phrase used to decrypt private key 
                                      certificates.  Note:  For now this parameter is not used
                                      we are loading PKCS7 keys, so a pass phrase is not required.

         @param sslType               Version of the TLS specification to use:  SSLv23 or TLSv1
      */      
      Transport* addTransport( TransportType protocol,
                         int port=0, 
                         IpVersion version=V4,
                         StunSetting stun=StunDisabled,
                         const Data& ipInterface = Data::Empty, 
                         const Data& sipDomainname = Data::Empty, // only used
                                                                  // for TLS
                                                                  // based stuff 
                         const Data& privateKeyPassPhrase = Data::Empty,
                         SecurityTypes::SSLType sslType = SecurityTypes::TLSv1);
      
      /**
          Used to plug-in custom transports.  Adds the transport to the Transport
          Selector.

          @param transport Pointer to an externally created transport.  SipStack 
                           assumes ownership.
      */
      void addTransport( std::auto_ptr<Transport> transport);
      
      /** 
          Returns the fifo that subclasses of Transport should use for the rxFifo
          cons. param.

          @returns A fifo of TransactionMessage's
      */
      Fifo<TransactionMessage>& stateMacFifo();      

      /**
          Used to add an alias for this sip element. e.g. foobar.com and boo.com
          are both handled by this proxy.  Not threadsafe.  Alias is added to 
          internal list of Domains and can be checked with isMyDomain.

          @param domain   Domain name that this stack is responsible for.

          @param port     Port for domain that this stack is responsible for.
      */
      void addAlias(const Data& domain, int port);
      
      /** 
          Returns true if domain is handled by this stack.  Convenience for
          Transaction Users. 

          @param domain   Domain name to check.

          @param port     Port number to check.
      */
      bool isMyDomain(const Data& domain, int port) const;
      
      /** 
          Get one of the names for this host (calls through to gethostbyname) and
          is not threadsafe.
      */
      static Data getHostname();

      /**
          Get one of the IP address for this host (calls through to gethostbyname) and
          is not threadsafe.
      */
      static Data getHostAddress();

      /** 
          Get one of the domains/ports that are handled by this stack in Uri form. 
          "sip:" scheme is assumed.
      */
      const Uri& getUri() const;

      /** 
          Interface for the TU to send a message.  Makes a copy of the
          SipMessage.  Caller is responsible for deleting the memory and may do
          so as soon as it returns.  Loose Routing processing as per RFC3261 must
          be done before calling send by the TU. See Helper::processStrictRoute

          @param msg SipMessage to send.

          @param tu  TransactionUser to send from.
      */
      void send(const SipMessage& msg, TransactionUser* tu=0);

      void send(std::auto_ptr<SipMessage> msg, TransactionUser* tu = 0);
      
      /** this is only if you want to send to a destination not in the route. You
          probably don't want to use it. */
      void sendTo(std::auto_ptr<SipMessage> msg, const Uri& uri, TransactionUser* tu=0);
      /** this is only if you want to send to a destination not in the route. You
          probably don't want to use it. */
      void sendTo(std::auto_ptr<SipMessage> msg, const Tuple& tuple, TransactionUser* tu=0);

      /**
          This is only if you want to send to a destination not in the route.
          Useful for implementing Outbound Proxy use.  Makes a copy of the
          SipMessage.  Caller is responsible for deleting the memory and may 
          do so as soon as it returns.

          @param msg SipMessage to send.

          @param uri Destination to send to, specified as a Uri.

          @param tu  TransactionUser to send from.
      */
      void sendTo(const SipMessage& msg, const Uri& uri, TransactionUser* tu=0);

      /**
          This is only if you want to send to a destination not in the route. 
          Useful for implementing Outbound Proxy use.  Makes a copy of the
          SipMessage.  Caller is responsible for deleting the memory and may 
          do so as soon as it returns.

          @param msg   SipMessage to send.

          @param tuple Destination to send to, specified as a Tuple.

          @param tu    TransactionUser to send from.
      */
      void sendTo(const SipMessage& msg, const Tuple& tuple,
                  TransactionUser* tu=0);

      /**
          This is only if you want to force send to only send over an existing 
          connection.  If there is no connection, then it will try the next tuple.  
          If there are no more Tuples to try, then a 503 is sent to the TU.  Makes 
          a copy of the SipMessage.  Caller is responsible for deleting the memory 
          and may  do so as soon as it returns.

          @param msg   SipMessage to send.

          @param tuple Destination to send to, specified as a Tuple.  A
                       connection to this destination must exist.  

          @param tu    TransactionUser to send from.
      */
      void sendOverExistingConnection(const SipMessage& msg, const Tuple& tuple,
                                      TransactionUser* tu=0);

      /**
          Makes the message available to the TU at some later time - specified in
          seconds.  
          Note:  TranasctionUser subclasses can just post to themselves.
          
          @param message ApplicationMessage to post

          @param secondsLater Number of seconds before message is to be posted.

          @param tu    TransactionUser to post to.
      */
      void post(const std::auto_ptr<ApplicationMessage> message, 
                unsigned int secondsLater,
                TransactionUser* tu=0);

      /**
          Makes the message available to the TU at some later time - specified in
          milli-seconds.  
          Note: TranasctionUser subclasses can just post to themselves.
          
          @param message ApplicationMessage to post

          @param ms      Number of milli-seconds before message is to be posted.

          @param tu      TransactionUser to post to.
      */
      void postMS(const std::auto_ptr<ApplicationMessage> message, 
                  unsigned int ms,
                  TransactionUser* tu=0);

      /**
          Makes the message available to the TU later.  Makes a copy of the
          Message.  Caller is responsible for deleting the memory and may 
          do so as soon as it returns.  Since the addition of TransactionUsers, 
          this method is deprecated.  Calling this will cause the TuSelector to 
          post to the old TuFifo that is not associated with any 
          TransactionUser.

          Note:  TranasctionUser subclasses can just post to themselves.
          
          @deprecated

          @param message ApplicationMessage to post
      */
      void post(const ApplicationMessage& message);

      /**
          Makes the message available to the TU at some later time - specified in
          seconds.  Makes a copy of the ApplicationMessage.  Caller is responsible 
          for deleting the memory and may do so as soon as it returns.  
          Note:  TranasctionUser subclasses can just post to themselves.