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 <memory> 26 #include <string> 27 #include <vector> 28 29 #include "absl/types/optional.h" 30 #include "api/rtc_error.h" 31 #include "rtc_base/ref_count.h" 32 #include "rtc_base/system/rtc_export.h" 33 34 namespace cricket { 35 class Candidate; 36 class SessionDescription; 37 } // namespace cricket 38 39 namespace webrtc { 40 41 struct SdpParseError { 42 public: 43 // The sdp line that causes the error. 44 std::string line; 45 // Explains the error. 46 std::string description; 47 }; 48 49 // Class representation of an ICE candidate. 50 // 51 // An instance of this interface is supposed to be owned by one class at 52 // a time and is therefore not expected to be thread safe. 53 // 54 // An instance can be created by CreateIceCandidate. 55 class RTC_EXPORT IceCandidateInterface { 56 public: ~IceCandidateInterface()57 virtual ~IceCandidateInterface() {} 58 // If present, this is the value of the "a=mid" attribute of the candidate's 59 // m= section in SDP, which identifies the m= section. 60 virtual std::string sdp_mid() const = 0; 61 // This indicates the index (starting at zero) of m= section this candidate 62 // is associated with. Needed when an endpoint doesn't support MIDs. 63 virtual int sdp_mline_index() const = 0; 64 // Only for use internally. 65 virtual const cricket::Candidate& candidate() const = 0; 66 // The URL of the ICE server which this candidate was gathered from. 67 // TODO(zhihuang): Remove the default implementation once the subclasses 68 // implement this method. 69 virtual std::string server_url() const; 70 // Creates a SDP-ized form of this candidate. 71 virtual bool ToString(std::string* out) const = 0; 72 }; 73 74 // Creates a IceCandidateInterface based on SDP string. 75 // Returns null if the sdp string can't be parsed. 76 // `error` may be null. 77 RTC_EXPORT IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid, 78 int sdp_mline_index, 79 const std::string& sdp, 80 SdpParseError* error); 81 82 // Creates an IceCandidateInterface based on a parsed candidate structure. 83 RTC_EXPORT std::unique_ptr<IceCandidateInterface> CreateIceCandidate( 84 const std::string& sdp_mid, 85 int sdp_mline_index, 86 const cricket::Candidate& candidate); 87 88 // This class represents a collection of candidates for a specific m= section. 89 // Used in SessionDescriptionInterface. 90 class IceCandidateCollection { 91 public: ~IceCandidateCollection()92 virtual ~IceCandidateCollection() {} 93 virtual size_t count() const = 0; 94 // Returns true if an equivalent `candidate` exist in the collection. 95 virtual bool HasCandidate(const IceCandidateInterface* candidate) const = 0; 96 virtual const IceCandidateInterface* at(size_t index) const = 0; 97 }; 98 99 // Enum that describes the type of the SessionDescriptionInterface. 100 // Corresponds to RTCSdpType in the WebRTC specification. 101 // https://w3c.github.io/webrtc-pc/#dom-rtcsdptype 102 enum class SdpType { 103 kOffer, // Description must be treated as an SDP offer. 104 kPrAnswer, // Description must be treated as an SDP answer, but not a final 105 // answer. 106 kAnswer, // Description must be treated as an SDP final answer, and the 107 // offer-answer exchange must be considered complete after 108 // receiving this. 109 kRollback // Resets any pending offers and sets signaling state back to 110 // stable. 111 }; 112 113 // Returns the string form of the given SDP type. String forms are defined in 114 // SessionDescriptionInterface. 115 RTC_EXPORT const char* SdpTypeToString(SdpType type); 116 117 // Returns the SdpType from its string form. The string form can be one of the 118 // constants defined in SessionDescriptionInterface. Passing in any other string 119 // results in nullopt. 120 absl::optional<SdpType> SdpTypeFromString(const std::string& type_str); 121 122 // Class representation of an SDP session description. 123 // 124 // An instance of this interface is supposed to be owned by one class at a time 125 // and is therefore not expected to be thread safe. 126 // 127 // An instance can be created by CreateSessionDescription. 128 class RTC_EXPORT SessionDescriptionInterface { 129 public: 130 // String representations of the supported SDP types. 131 static const char kOffer[]; 132 static const char kPrAnswer[]; 133 static const char kAnswer[]; 134 static const char kRollback[]; 135 ~SessionDescriptionInterface()136 virtual ~SessionDescriptionInterface() {} 137 138 // Create a new SessionDescriptionInterface object 139 // with the same values as the old object. 140 // TODO(bugs.webrtc.org:12215): Remove default implementation Clone()141 virtual std::unique_ptr<SessionDescriptionInterface> Clone() const { 142 return nullptr; 143 } 144 145 // Only for use internally. 146 virtual cricket::SessionDescription* description() = 0; 147 virtual const cricket::SessionDescription* description() const = 0; 148 149 // Get the session id and session version, which are defined based on 150 // RFC 4566 for the SDP o= line. 151 virtual std::string session_id() const = 0; 152 virtual std::string session_version() const = 0; 153 154 // Returns the type of this session description as an SdpType. Descriptions of 155 // the various types are found in the SdpType documentation. 156 // TODO(steveanton): Remove default implementation once Chromium has been 157 // updated. 158 virtual SdpType GetType() const; 159 160 // kOffer/kPrAnswer/kAnswer 161 // TODO(steveanton): Remove this in favor of `GetType` that returns SdpType. 162 virtual std::string type() const = 0; 163 164 // Adds the specified candidate to the description. 165 // 166 // Ownership is not transferred. 167 // 168 // Returns false if the session description does not have a media section 169 // that corresponds to `candidate.sdp_mid()` or 170 // `candidate.sdp_mline_index()`. 171 virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0; 172 173 // Removes the candidates from the description, if found. 174 // 175 // Returns the number of candidates removed. 176 virtual size_t RemoveCandidates( 177 const std::vector<cricket::Candidate>& candidates); 178 179 // Returns the number of m= sections in the session description. 180 virtual size_t number_of_mediasections() const = 0; 181 182 // Returns a collection of all candidates that belong to a certain m= 183 // section. 184 virtual const IceCandidateCollection* candidates( 185 size_t mediasection_index) const = 0; 186 187 // Serializes the description to SDP. 188 virtual bool ToString(std::string* out) const = 0; 189 }; 190 191 // Creates a SessionDescriptionInterface based on the SDP string and the type. 192 // Returns null if the sdp string can't be parsed or the type is unsupported. 193 // `error` may be null. 194 // TODO(steveanton): This function is deprecated. Please use the functions below 195 // which take an SdpType enum instead. Remove this once it is no longer used. 196 RTC_EXPORT SessionDescriptionInterface* CreateSessionDescription( 197 const std::string& type, 198 const std::string& sdp, 199 SdpParseError* error); 200 201 // Creates a SessionDescriptionInterface based on the SDP string and the type. 202 // Returns null if the SDP string cannot be parsed. 203 // If using the signature with `error_out`, details of the parsing error may be 204 // written to `error_out` if it is not null. 205 RTC_EXPORT std::unique_ptr<SessionDescriptionInterface> 206 CreateSessionDescription(SdpType type, const std::string& sdp); 207 RTC_EXPORT std::unique_ptr<SessionDescriptionInterface> 208 CreateSessionDescription(SdpType type, 209 const std::string& sdp, 210 SdpParseError* error_out); 211 212 // Creates a SessionDescriptionInterface based on a parsed SDP structure and the 213 // given type, ID and version. 214 std::unique_ptr<SessionDescriptionInterface> CreateSessionDescription( 215 SdpType type, 216 const std::string& session_id, 217 const std::string& session_version, 218 std::unique_ptr<cricket::SessionDescription> description); 219 220 // CreateOffer and CreateAnswer callback interface. 221 class RTC_EXPORT CreateSessionDescriptionObserver 222 : public rtc::RefCountInterface { 223 public: 224 // This callback transfers the ownership of the `desc`. 225 // TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion 226 // around ownership. 227 virtual void OnSuccess(SessionDescriptionInterface* desc) = 0; 228 // The OnFailure callback takes an RTCError, which consists of an 229 // error code and a string. 230 // RTCError is non-copyable, so it must be passed using std::move. 231 // Earlier versions of the API used a string argument. This version 232 // is removed; its functionality was the same as passing 233 // error.message. 234 virtual void OnFailure(RTCError error) = 0; 235 236 protected: 237 ~CreateSessionDescriptionObserver() override = default; 238 }; 239 240 // SetLocalDescription and SetRemoteDescription callback interface. 241 class RTC_EXPORT SetSessionDescriptionObserver : public rtc::RefCountInterface { 242 public: 243 virtual void OnSuccess() = 0; 244 // See description in CreateSessionDescriptionObserver for OnFailure. 245 virtual void OnFailure(RTCError error) = 0; 246 247 protected: 248 ~SetSessionDescriptionObserver() override = default; 249 }; 250 251 } // namespace webrtc 252 253 #endif // API_JSEP_H_ 254