1 /* 2 * Copyright 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 // This file contains declarations of interfaces that wrap SDP-related 12 // constructs; session descriptions and ICE candidates. The inner "cricket::" 13 // objects shouldn't be accessed directly; the intention is that an application 14 // using the PeerConnection API only creates these objects from strings, and 15 // them passes them into the PeerConnection. 16 // 17 // Though in the future, we're planning to provide an SDP parsing API, with a 18 // structure more friendly than cricket::SessionDescription. 19 20 #ifndef API_JSEP_H_ 21 #define API_JSEP_H_ 22 23 #include <stddef.h> 24 25 #include <string> 26 #include <vector> 27 28 #include "rtc_base/refcount.h" 29 30 namespace cricket { 31 class Candidate; 32 class SessionDescription; 33 } // namespace cricket 34 35 namespace webrtc { 36 37 struct SdpParseError { 38 public: 39 // The sdp line that causes the error. 40 std::string line; 41 // Explains the error. 42 std::string description; 43 }; 44 45 // Class representation of an ICE candidate. 46 // 47 // An instance of this interface is supposed to be owned by one class at 48 // a time and is therefore not expected to be thread safe. 49 // 50 // An instance can be created by CreateIceCandidate. 51 class IceCandidateInterface { 52 public: ~IceCandidateInterface()53 virtual ~IceCandidateInterface() {} 54 // If present, this is the value of the "a=mid" attribute of the candidate's 55 // m= section in SDP, which identifies the m= section. 56 virtual std::string sdp_mid() const = 0; 57 // This indicates the index (starting at zero) of m= section this candidate 58 // is assocated with. Needed when an endpoint doesn't support MIDs. 59 virtual int sdp_mline_index() const = 0; 60 // Only for use internally. 61 virtual const cricket::Candidate& candidate() const = 0; 62 // The URL of the ICE server which this candidate was gathered from. 63 // TODO(zhihuang): Remove the default implementation once the subclasses 64 // implement this method. server_url()65 virtual std::string server_url() const { return ""; } 66 // Creates a SDP-ized form of this candidate. 67 virtual bool ToString(std::string* out) const = 0; 68 }; 69 70 // Creates a IceCandidateInterface based on SDP string. 71 // Returns null if the sdp string can't be parsed. 72 // |error| may be null. 73 IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid, 74 int sdp_mline_index, 75 const std::string& sdp, 76 SdpParseError* error); 77 78 // This class represents a collection of candidates for a specific m= section. 79 // Used in SessionDescriptionInterface. 80 class IceCandidateCollection { 81 public: ~IceCandidateCollection()82 virtual ~IceCandidateCollection() {} 83 virtual size_t count() const = 0; 84 // Returns true if an equivalent |candidate| exist in the collection. 85 virtual bool HasCandidate(const IceCandidateInterface* candidate) const = 0; 86 virtual const IceCandidateInterface* at(size_t index) const = 0; 87 }; 88 89 // Class representation of an SDP session description. 90 // 91 // An instance of this interface is supposed to be owned by one class at a time 92 // and is therefore not expected to be thread safe. 93 // 94 // An instance can be created by CreateSessionDescription. 95 class SessionDescriptionInterface { 96 public: 97 // Supported types: 98 static const char kOffer[]; 99 static const char kPrAnswer[]; 100 static const char kAnswer[]; 101 ~SessionDescriptionInterface()102 virtual ~SessionDescriptionInterface() {} 103 104 // Only for use internally. 105 virtual cricket::SessionDescription* description() = 0; 106 virtual const cricket::SessionDescription* description() const = 0; 107 108 // Get the session id and session version, which are defined based on 109 // RFC 4566 for the SDP o= line. 110 virtual std::string session_id() const = 0; 111 virtual std::string session_version() const = 0; 112 113 // kOffer/kPrAnswer/kAnswer 114 virtual std::string type() const = 0; 115 116 // Adds the specified candidate to the description. 117 // 118 // Ownership is not transferred. 119 // 120 // Returns false if the session description does not have a media section 121 // that corresponds to |candidate.sdp_mid()| or 122 // |candidate.sdp_mline_index()|. 123 virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0; 124 125 // Removes the candidates from the description, if found. 126 // 127 // Returns the number of candidates removed. RemoveCandidates(const std::vector<cricket::Candidate> & candidates)128 virtual size_t RemoveCandidates( 129 const std::vector<cricket::Candidate>& candidates) { return 0; } 130 131 // Returns the number of m= sections in the session description. 132 virtual size_t number_of_mediasections() const = 0; 133 134 // Returns a collection of all candidates that belong to a certain m= 135 // section. 136 virtual const IceCandidateCollection* candidates( 137 size_t mediasection_index) const = 0; 138 139 // Serializes the description to SDP. 140 virtual bool ToString(std::string* out) const = 0; 141 }; 142 143 // Creates a SessionDescriptionInterface based on the SDP string and the type. 144 // Returns null if the sdp string can't be parsed or the type is unsupported. 145 // |error| may be null. 146 SessionDescriptionInterface* CreateSessionDescription(const std::string& type, 147 const std::string& sdp, 148 SdpParseError* error); 149 150 // CreateOffer and CreateAnswer callback interface. 151 class CreateSessionDescriptionObserver : public rtc::RefCountInterface { 152 public: 153 // This callback transfers the ownership of the |desc|. 154 // TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion 155 // around ownership. 156 virtual void OnSuccess(SessionDescriptionInterface* desc) = 0; 157 virtual void OnFailure(const std::string& error) = 0; 158 159 protected: ~CreateSessionDescriptionObserver()160 ~CreateSessionDescriptionObserver() {} 161 }; 162 163 // SetLocalDescription and SetRemoteDescription callback interface. 164 class SetSessionDescriptionObserver : public rtc::RefCountInterface { 165 public: 166 virtual void OnSuccess() = 0; 167 virtual void OnFailure(const std::string& error) = 0; 168 169 protected: ~SetSessionDescriptionObserver()170 ~SetSessionDescriptionObserver() {} 171 }; 172 173 } // namespace webrtc 174 175 #endif // API_JSEP_H_ 176