Home | History | Annotate | Download | only in webrtc 
      1 /*
      2  * libjingle
      3  * Copyright 2012, Google Inc.
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions are met:
      7  *
      8  *  1. Redistributions of source code must retain the above copyright notice,
      9  *     this list of conditions and the following disclaimer.
     10  *  2. Redistributions in binary form must reproduce the above copyright notice,
     11  *     this list of conditions and the following disclaimer in the documentation
     12  *     and/or other materials provided with the distribution.
     13  *  3. The name of the author may not be used to endorse or promote products
     14  *     derived from this software without specific prior written permission.
     15  *
     16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
     17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
     19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
     22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
     23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     26  */
     27 
     28 // Interfaces matching the draft-ietf-rtcweb-jsep-01.
     29 
     30 #ifndef TALK_APP_WEBRTC_JSEP_H_
     31 #define TALK_APP_WEBRTC_JSEP_H_
     32 
     33 #include <string>
     34 #include <vector>
     35 
     36 #include "talk/base/basictypes.h"
     37 #include "talk/base/refcount.h"
     38 
     39 namespace cricket {
     40 class SessionDescription;
     41 class Candidate;
     42 }  // namespace cricket
     43 
     44 namespace webrtc {
     45 
     46 struct SdpParseError {
     47  public:
     48   // The sdp line that causes the error.
     49   std::string line;
     50   // Explains the error.
     51   std::string description;
     52 };
     53 
     54 // Class representation of an ICE candidate.
     55 // An instance of this interface is supposed to be owned by one class at
     56 // a time and is therefore not expected to be thread safe.
     57 class IceCandidateInterface {
     58  public:
     59   virtual ~IceCandidateInterface() {}
     60   /// If present, this contains the identierfier of the "media stream
     61   // identification" as defined in [RFC 3388] for m-line this candidate is
     62   // assocated with.
     63   virtual std::string sdp_mid() const = 0;
     64   // This indeicates the index (starting at zero) of m-line in the SDP this
     65   // candidate is assocated with.
     66   virtual int sdp_mline_index() const = 0;
     67   virtual const cricket::Candidate& candidate() const = 0;
     68   // Creates a SDP-ized form of this candidate.
     69   virtual bool ToString(std::string* out) const = 0;
     70 };
     71 
     72 // Creates a IceCandidateInterface based on SDP string.
     73 // Returns NULL if the sdp string can't be parsed.
     74 // TODO(ronghuawu): Deprecated.
     75 IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
     76                                           int sdp_mline_index,
     77                                           const std::string& sdp);
     78 
     79 // |error| can be NULL if doesn't care about the failure reason.
     80 IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
     81                                           int sdp_mline_index,
     82                                           const std::string& sdp,
     83                                           SdpParseError* error);
     84 
     85 // This class represents a collection of candidates for a specific m-line.
     86 // This class is used in SessionDescriptionInterface to represent all known
     87 // candidates for a certain m-line.
     88 class IceCandidateCollection {
     89  public:
     90   virtual ~IceCandidateCollection() {}
     91   virtual size_t count() const = 0;
     92   // Returns true if an equivalent |candidate| exist in the collection.
     93   virtual bool HasCandidate(const IceCandidateInterface* candidate) const = 0;
     94   virtual const IceCandidateInterface* at(size_t index) const = 0;
     95 };
     96 
     97 // Class representation of a Session description.
     98 // An instance of this interface is supposed to be owned by one class at
     99 // a time and is therefore not expected to be thread safe.
    100 class SessionDescriptionInterface {
    101  public:
    102   // Supported types:
    103   static const char kOffer[];
    104   static const char kPrAnswer[];
    105   static const char kAnswer[];
    106 
    107   virtual ~SessionDescriptionInterface() {}
    108   virtual cricket::SessionDescription* description() = 0;
    109   virtual const cricket::SessionDescription* description() const = 0;
    110   // Get the session id and session version, which are defined based on
    111   // RFC 4566 for the SDP o= line.
    112   virtual std::string session_id() const = 0;
    113   virtual std::string session_version() const = 0;
    114   virtual std::string type() const = 0;
    115   // Adds the specified candidate to the description.
    116   // Ownership is not transferred.
    117   // Returns false if the session description does not have a media section that
    118   // corresponds to the |candidate| label.
    119   virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0;
    120   // Returns the number of m- lines in the session description.
    121   virtual size_t number_of_mediasections() const = 0;
    122   // Returns a collection of all candidates that belong to a certain m-line
    123   virtual const IceCandidateCollection* candidates(
    124       size_t mediasection_index) const = 0;
    125   // Serializes the description to SDP.
    126   virtual bool ToString(std::string* out) const = 0;
    127 };
    128 
    129 // Creates a SessionDescriptionInterface based on SDP string and the type.
    130 // Returns NULL if the sdp string can't be parsed or the type is unsupported.
    131 // TODO(ronghuawu): Deprecated.
    132 SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
    133                                                       const std::string& sdp);
    134 
    135 // |error| can be NULL if doesn't care about the failure reason.
    136 SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
    137                                                       const std::string& sdp,
    138                                                       SdpParseError* error);
    139 
    140 // Jsep CreateOffer and CreateAnswer callback interface.
    141 class CreateSessionDescriptionObserver : public talk_base::RefCountInterface {
    142  public:
    143   // The implementation of the CreateSessionDescriptionObserver takes
    144   // the ownership of the |desc|.
    145   virtual void OnSuccess(SessionDescriptionInterface* desc) = 0;
    146   virtual void OnFailure(const std::string& error) = 0;
    147 
    148  protected:
    149   ~CreateSessionDescriptionObserver() {}
    150 };
    151 
    152 // Jsep SetLocalDescription and SetRemoteDescription callback interface.
    153 class SetSessionDescriptionObserver : public talk_base::RefCountInterface {
    154  public:
    155   virtual void OnSuccess() = 0;
    156   virtual void OnFailure(const std::string& error) = 0;
    157 
    158  protected:
    159   ~SetSessionDescriptionObserver() {}
    160 };
    161 
    162 }  // namespace webrtc
    163 
    164 #endif  // TALK_APP_WEBRTC_JSEP_H_
    165