helper.hxx

这是国外的resip协议栈

          @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.

          @param target Ends up in the RequestURI and To header

          @param from   Ends up in the From header

          @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, MethodTypes method);

      /**
          Make a new Cancel request for the specified request.  Caller owns the 
          returned pointer and is responsible for deleting it.

          @param request Request for which the Cancel will apply. ie. Invite request.

          @returns Created Cancel request.  Caller must deallocate.         
      */
      static SipMessage* makeCancel(const SipMessage& request);
      
      /// Create a Register request with an overriden Contact.  See makeRequest.
      static SipMessage* makeRegister(const NameAddr& to, const NameAddr& from, const NameAddr& contact);

      /// Create a Register request with an empty Contact.  See makeRequest.
      static SipMessage* makeRegister(const NameAddr& to, const NameAddr& from);

      /// Create a Register request with an overriden Contact, transport is added to Request URI.  See makeRequest.
      static SipMessage* makeRegister(const NameAddr& to, const Data& transport, const NameAddr& contact);

      /// Create a Register request with an empty Contact, transport is added to Request URI.  See makeRequest.
      static SipMessage* makeRegister(const NameAddr& to, const Data& transport);

      /// Create a Subscribe request with an overriden Contact.  See makeRequest.
      static SipMessage* makeSubscribe(const NameAddr& target, const NameAddr& from, const NameAddr& contact);

      /// Create a Subscribe request with an empty Contact.  See makeRequest.
      static SipMessage* makeSubscribe(const NameAddr& target, const NameAddr& from);

      /// Create a Message request with an overriden Contact.  See makeRequest.
      static SipMessage* makeMessage(const NameAddr& target, const NameAddr& from, const NameAddr& contact);

      /// Create a Message request with an empty Contact.  See makeRequest.
      static SipMessage* makeMessage(const NameAddr& target, const NameAddr& from);

      /// Create a Publish request with an overriden Contact.  See makeRequest.
      static SipMessage* makePublish(const NameAddr& target, const NameAddr& from, const NameAddr& contact);

      /// Create a Publish request with an empty Contact.  See makeRequest.
      static SipMessage* makePublish(const NameAddr& target, const NameAddr& from);

      /**
          This interface should be used by the stack (TransactionState) to create an
          AckMsg to a failure response.  See RFC3261 section 17.1.1.3.  Caller owns the 
          returned pointer and is responsible for deleting it.
          
          @note The branch in this ACK needs to be the one from the request. 
                For TU generated ACK, see Dialog::makeAck(...)

          @param request Request that this ACK applies to.

          @param response Response that we are ACKing - required so that we can get the To tag
                          into the generated ACK.

          @returns Created Ack request.  Caller must deallocate.         
       */
      static SipMessage* makeFailureAck(const SipMessage& request, const SipMessage& response);

      /** 
          Creates and returns a unique branch parameter.  Generated branch will contain
          the RFC3261 magic cookie + 4 randome hex characters + "C1" + 2 random hex characters.

          @deprecated Not used by stack.
      */
      static Data computeUniqueBranch();
      static Data computeProxyBranch(const SipMessage& request);

      static Data computeCallId();
      static Data computeTag(int numBytes);

      enum AuthResult {Failed = 1, Authenticated, Expired, BadlyFormed};

      static AuthResult authenticateRequest(const SipMessage& request, 
                                            const Data& realm,
                                            const Data& password,
                                            int expiresDelta = 0);

      static AuthResult authenticateRequestWithA1(const SipMessage& request, 
                                                  const Data& realm,
                                                  const Data& hA1,
                                                  int expiresDelta = 0);
      
      static std::pair<AuthResult,Data> 
                advancedAuthenticateRequest(const SipMessage& request, 
                                            const Data& realm,
                                            const Data& a1,
                                            int expiresDelta = 0,
                                            bool proxyAuthorization = true);
      
      // create a 407 response with Proxy-Authenticate header filled in
      static SipMessage* makeProxyChallenge(const SipMessage& request, 
                                            const Data& realm,
                                            bool useAuth = true,
                                            bool stale = false);

      //create a 401 response with WWW-Authenticate header filled in
      static SipMessage* makeWWWChallenge(const SipMessage& request, 
                                            const Data& realm,
                                            bool useAuth = true,
                                            bool stale = false);

      // create a 401 or 407 response with Proxy-Authenticate or Authenticate header 
      // filled in
      static SipMessage* makeChallenge(const SipMessage& request, 
                                       const Data& realm,
                                       bool useAuth = true,
                                       bool stale = false,
                                       bool proxy = false);

      static bool algorithmAndQopSupported(const Auth& challenge);
      

      // adds authorization headers in reponse to the 401 or 407--currently
      // only supports md5.
      static SipMessage& addAuthorization(SipMessage& request,
                                          const SipMessage& challenge,
                                          const Data& username,
                                          const Data& password,
                                          const Data& cnonce,
                                          unsigned int& nonceCount);

      static Auth makeChallengeResponseAuth(SipMessage& request,
                                            const Data& username,
                                            const Data& password,
                                            const Auth& challenge,
                                            const Data& cnonce,
                                            unsigned int& nonceCount,
                                            Data& nonceCountString);      

      static Auth makeChallengeResponseAuthWithA1(const SipMessage& request,
                                                  const Data& username,
                                                  const Data& passwordHashA1,
                                                  const Auth& challenge,
                                                  const Data& cnonce,
                                                  unsigned int& nonceCount,
                                                  Data& nonceCountString);      

      static Data makeResponseMD5WithA1(const Data& a1,
                                        const Data& method, const Data& digestUri, const Data& nonce,
                                        const Data& qop = Data::Empty, const Data& cnonce = Data::Empty, 
                                        const Data& cnonceCount = Data::Empty, const Contents *entityBody = 0);

      static Data makeResponseMD5(const Data& username, const Data& password, const Data& realm, 
                                  const Data& method, const Data& digestUri, const Data& nonce,
                                  const Data& qop = Data::Empty, const Data& cnonce = Data::Empty, 
                                  const Data& cnonceCount = Data::Empty, const Contents *entityBody = 0);
      
      /// Note: Helper assumes control of NonceHelper object and will delete when global scope is cleaned up      
      static void setNonceHelper(NonceHelper *nonceHelper);
      static NonceHelper* getNonceHelper();
      static Data makeNonce(const SipMessage& request, const Data& timestamp);

      static Uri makeUri(const Data& aor, const Data& scheme=Symbols::DefaultSipScheme);

      static void processStrictRoute(SipMessage& request);

      // return the port that the response should be sent to using rules from 
      // RFC 3261 - 18.2.2
      static int getPortForReply(SipMessage& request);

      static void massageRoute(const SipMessage& request, NameAddr& route);

      static Uri fromAor(const Data& aor, const Data& scheme=Symbols::DefaultSipScheme);

      // Do basic checks to validate a received message off the wire
      // If the basic check fails, and reason is non-null, reason will be set
      // to the reason the check failed. This function does not take ownership
      // of reason.
      static bool validateMessage(const SipMessage& message,resip::Data* reason=0);

      // GRUU support -- reversibly and opaquely combine instance id and aor
      static Data gruuUserPart(const Data& instanceId,
                               const Data& aor,
                               const Data& key);

      // GRUU support -- extract instance id and aor from user portion
      static std::pair<Data,Data> fromGruuUserPart(const Data& gruuUserPart,
                                                   const Data& key);

      struct ContentsSecAttrs
      {
            ContentsSecAttrs();
            ContentsSecAttrs(std::auto_ptr<Contents> contents,
                             std::auto_ptr<SecurityAttributes> attributes);
            ContentsSecAttrs(const ContentsSecAttrs& rhs);
            ContentsSecAttrs& operator=(const ContentsSecAttrs& rhs);
            mutable std::auto_ptr<Contents> mContents;
            mutable std::auto_ptr<SecurityAttributes> mAttributes;
      };

      static ContentsSecAttrs extractFromPkcs7(const SipMessage& message, Security& security);

      
      enum FailureMessageEffect{ DialogTermination, TransactionTermination, UsageTermination, 
                                 RetryAfter, OptionalRetryAfter, ApplicationDependant };
      
      static FailureMessageEffect determineFailureMessageEffect(const SipMessage& response);      

      // Just simply walk the contents tree and return the first SdpContents in
      // the tree.
      static std::auto_ptr<SdpContents> getSdp(Contents* tree);

   private:
      static Data qopOption(const Auth& challenge);
      class NonceHelperPtr
      {
         public:
            NonceHelperPtr() : mNonceHelper(0) {}
            ~NonceHelperPtr() { delete mNonceHelper; }
            NonceHelper *mNonceHelper;
      };
      static NonceHelperPtr mNonceHelperPtr;
};

}

#endif

/* ====================================================================
 * The Vovida Software License, Version 1.0 
 * 
 * Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 
 * 3. The names "VOCAL", "Vovida Open Communication Application Library",
 *    and "Vovida Open Communication Application Library (VOCAL)" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact [e-mail].
 *
 * 4. Products derived from this software may not be called "VOCAL", nor
 *    may "VOCAL" appear in their name, without prior written
 *    permission of Vovida Networks, Inc.
 * 
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
 * NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
 * NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
 * IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 * 
 * ====================================================================
 * 
 * This software consists of voluntary contributions made by Vovida
 * Networks, Inc. and many individuals on behalf of Vovida Networks,
 * Inc.  For more information on Vovida Networks, Inc., please see
 * <http://www.vovida.org/>.
 *
 */