helper.hxx

一个著名的SIP协议栈

#if !defined(RESIP_HELPER_HXX)
#define RESIP_HELPER_HXX 

#include <time.h>

#include "resip/stack/NonceHelper.hxx"
#include "resip/stack/Symbols.hxx"
#include "resip/stack/Uri.hxx"
#include "resip/stack/MethodTypes.hxx"
#include "rutil/BaseException.hxx"
#include "rutil/Data.hxx"
#include "resip/stack/Contents.hxx"
#include "resip/stack/SecurityAttributes.hxx"
#include "resip/stack/SdpContents.hxx"

namespace resip
{

class SipMessage;
class NameAddr;
class SecurityAttributes;
class Security;

class UnsupportedAuthenticationScheme : public BaseException
{
   public:
      UnsupportedAuthenticationScheme(const Data& msg, const Data& file, const int line)
         : BaseException(msg, file, line) {}
      
      const char* name() const { return "UnsupportedAuthenticationScheme"; }
};

class Helper
{
   public:

      /// bytes in to-tag& from-tag, should prob. live somewhere else
      const static int tagSize;  

      /** 
          Used by Registration, Publication and Subscription refreshes, to
          calculate the time at which a refresh should be performed (which
          is some time, that is a bit smaller than the Expiration interval).
          The recommended caluclation from the RFC's is the minimnum of the 
          Exipiration interval less 5 seconds and nine tenths of the exipiration 
          interval.
      */
      template<typename T>
      static T aBitSmallerThan(T secs)
      {
         return resipMax(T(0), resipMin(T(secs-5), T(9*secs/10)));
      }

      /**
           Used to jitter the expires in a SUBSCRIBE or REGISTER expires header

           @param input            Value to jitter

           @param lowerPercentage  The lower range of the random percentage by which 
                                   to jitter the value by.

           @param upperPercentage  The upper range of the random percentage by which
                                   to jitter the value by.  Must be greater than or equal 
                                   to lowerPercentage

           @param minimum          Only jitter the input if greater than minimum
       */
      static int jitterValue(int input, int lowerPercentage, int upperPercentage, int minimum=0);

      /**
          Make an invite request - Empty Contact and Via is added and will be populated 
          by the stack when sent.
            
          @param target Ends up in the RequestURI and To header

          @param from   Ends up in the From header
      */
      static SipMessage* makeInvite(const NameAddr& target, const NameAddr& from);
      
      /**
          Make an invite request using a overridden contact header - Empty Via is added 
          and will be populated by the stack when sent.
            
          @param target Ends up in the RequestURI and To header

          @param from   Ends up in the From header

          @param contact Ends up in the Contact header.  Stack will not change this
                         when sent.
      */
      static SipMessage* makeInvite(const NameAddr& target, const NameAddr& from, const NameAddr& contact);
      
      /**
          Make a response to a provided request.  Adds a To tag, Contact and Record-Route
          headers appropriately.
            
          @param response SipMessage populated with the appropriate response

          @param request  SipMessage request from which to generate the response

          @param responseCode Response code to use on status line.

          @param reason   Optional reason string to use on status line.  If not provided
                          then a default reason string will be added for well defined
                          response codes.

          @param hostname Optional hostname to use in Warning header.  Only used if
                          warning is also provided.

          @param warning  Optional warning text.  If present a Warning header is added
                          and hostname is used in warning header.
      */
      static void makeResponse(SipMessage& response, 
                               const SipMessage& request, 
                               int responseCode, 
                               const Data& reason = Data::Empty,
                               const Data& hostname = Data::Empty,
                               const Data& warning=Data::Empty);

      /**
          Make a response to a provided request with an overridden Contact.  
          Adds a To tag, Contact and Record-Route headers appropriately.
            
          @param response SipMessage populated with the appropriate response

          @param request  SipMessage request from which to generate the response

          @param responseCode Response code to use on status line.

          @param myContact Contact header to add to response.

          @param reason   Optional reason string to use on status line.  If not provided
                          then a default reason string will be added for well defined
                          response codes.

          @param hostname Optional hostname to use in Warning header.  Only used if
                          warning is also provided.

          @param warning  Optional warning text.  If present a Warning header is added
                          and hostname is used in warning header.
      */
      static void makeResponse(SipMessage& response, 
                               const SipMessage& request, 
                               int responseCode, 
                               const NameAddr& myContact, 
                               const Data& reason = Data::Empty,
                               const Data& hostname = Data::Empty,
                               const Data& warning=Data::Empty);

      /**
          Make a new response to a provided request.  Adds a To tag, Contact and 
          Record-Route headers appropriately.  Caller owns the returned pointer and
          is responsible for deleting it.
            
          @param request  SipMessage request from which to generate the response

          @param responseCode Response code to use on status line.

          @param reason   Optional reason string to use on status line.  If not provided
                          then a default reason string will be added for well defined
                          response codes.

          @param hostname Optional hostname to use in Warning header.  Only used if
                          warning is also provided.

          @param warning  Optional warning text.  If present a Warning header is added
                          and hostname is used in warning header

          @returns SipMessage populated with the appropriate response.
                   Caller must deallocate.
      */
      static SipMessage* makeResponse(const SipMessage& request,
                                      int responseCode,
                                      const Data& reason = Data::Empty, 
                                      const Data& hostname = Data::Empty,
                                      const Data& warning=Data::Empty);

      /**
          Make a new response to a provided request with an overridden Contact.  
          Adds a To tag, Contact and Record-Route headers appropriately.
          Caller owns the returned pointer and is responsible for deleting it.

          @param request  SipMessage request from which to generate the response

          @param responseCode Response code to use on status line.

          @param myContact Contact header to add to response.

          @param reason   Optional reason string to use on status line.  If not provided
                          then a default reason string will be added for well defined
                          response codes.

          @param hostname Optional hostname to use in Warning header.  Only used if
                          warning is also provided.

          @param warning  Optional warning text.  If present a Warning header is added
                          and hostname is used in warning header.

          @returns SipMessage populated with the appropriate response.
                   Caller must deallocate.
      */
      static SipMessage* makeResponse(const SipMessage& request, 
                                      int responseCode, 
                                      const NameAddr& myContact, 
                                      const Data& reason = Data::Empty,
                                      const Data& hostname = Data::Empty,
                                      const Data& warning=Data::Empty);


      /**
          Make a 405 response to a provided request.  Allows header is added
          with specified methods, or with all methods the stack knows about.
          Caller owns the returned pointer and is responsible for deleting it.

          @param request  SipMessage request from which to generate the response

          @param allowedMethods Array of integers representing a list of Method 
                                Types to add to the generated Allows header. 
                                See MethodTypes.hxx.

          @param nMethods Number of methods specified in the allowedMethods 
                          integer array.  Specify -1 to have this method fill
                          in the Allows header automatically with each method
                          supported by the stack.

          @returns SipMessage populated with the appropriate response.    
                   Caller must deallocate.
      */
      static SipMessage* make405(const SipMessage& request,
                                 const int* allowedMethods = 0,
                                 int nMethods = -1);

      /**
          Returns the default reason string for a particular response code.

          @param responseCode  Response code to get reason for

          @param reason Data where the reason string associated with the 
                   responseCode will be set.
      */
      static void getResponseCodeReason(int responseCode, Data& reason);

      /**
          Make a new request with a overridden Contact.  To, maxforward=70, requestline 
          created, cseq method set, cseq sequence is 1, from and from tag set, contact 
          set, CallId created.  Caller owns the returned pointer and is responsible for 
          deleting it.

          @note While contact is only necessary for requests that establish a dialog,
                those are the requests most likely created by this method, others will
                be generated by the dialog.

          @param target Ends up in the RequestURI and To header

          @param from   Ends up in the From header

          @param contact Ends up in the Contact header.  Stack will not change this
                         when sent.

          @param method Type of request to create.  Methos is used in the Request Line
                        and the CSeq.

          @returns SipMessage request created.  Caller must deallocate.         
      */
      static SipMessage* makeRequest(const NameAddr& target, const NameAddr& from, const NameAddr& contact, MethodTypes method);

      /**
          Make a new request.  To, maxforward=70, requestline created, cseq method set, 
          cseq sequence is 1, from and from tag set, CallId created.  Caller owns the 
          returned pointer and is responsible for deleting it.

          @note An empty contact header is added.  This signals to the stack that it
                should be populated by the transports when sent.