blob: 6da782748d4be2175de026e6f9903ac1dd23f873 [file] [log] [blame]
henrike@webrtc.org28e20752013-07-10 00:45:361/*
kjellanderb24317b2016-02-10 15:54:432 * Copyright 2012 The WebRTC project authors. All Rights Reserved.
henrike@webrtc.org28e20752013-07-10 00:45:363 *
kjellanderb24317b2016-02-10 15:54:434 * 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.
henrike@webrtc.org28e20752013-07-10 00:45:369 */
10
deadbeefb10f32f2017-02-08 09:38:2111// 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.
henrike@webrtc.org28e20752013-07-10 00:45:3619
Mirko Bonadei92ea95e2017-09-15 04:47:3120#ifndef API_JSEP_H_
21#define API_JSEP_H_
henrike@webrtc.org28e20752013-07-10 00:45:3622
pbos9baddf22017-01-02 14:44:4123#include <stddef.h>
24
Steve Anton88f2cb92017-12-05 20:47:3225#include <memory>
henrike@webrtc.org28e20752013-07-10 00:45:3626#include <string>
27#include <vector>
28
Danil Chapovalov0bc58cf2018-06-21 11:32:5629#include "absl/types/optional.h"
Steve Anton10542f22019-01-11 17:11:0030#include "api/rtc_error.h"
31#include "rtc_base/ref_count.h"
Mirko Bonadei3b56ee72018-10-15 15:15:1232#include "rtc_base/system/rtc_export.h"
henrike@webrtc.org28e20752013-07-10 00:45:3633
34namespace cricket {
tommi6f59a4f2016-03-11 22:05:0935class Candidate;
Honghai Zhang7fb69db2016-03-14 18:59:1836class SessionDescription;
henrike@webrtc.org28e20752013-07-10 00:45:3637} // namespace cricket
38
39namespace webrtc {
40
41struct 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.
deadbeefb10f32f2017-02-08 09:38:2150//
henrike@webrtc.org28e20752013-07-10 00:45:3651// 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.
deadbeefb10f32f2017-02-08 09:38:2153//
54// An instance can be created by CreateIceCandidate.
henrike@webrtc.org28e20752013-07-10 00:45:3655class IceCandidateInterface {
56 public:
57 virtual ~IceCandidateInterface() {}
deadbeefb10f32f2017-02-08 09:38:2158 // 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.
henrike@webrtc.org28e20752013-07-10 00:45:3660 virtual std::string sdp_mid() const = 0;
deadbeefb10f32f2017-02-08 09:38:2161 // This indicates the index (starting at zero) of m= section this candidate
Steve Anton88f2cb92017-12-05 20:47:3262 // is associated with. Needed when an endpoint doesn't support MIDs.
henrike@webrtc.org28e20752013-07-10 00:45:3663 virtual int sdp_mline_index() const = 0;
deadbeefb10f32f2017-02-08 09:38:2164 // Only for use internally.
henrike@webrtc.org28e20752013-07-10 00:45:3665 virtual const cricket::Candidate& candidate() const = 0;
zhihuangd7e771d2017-02-16 19:29:3966 // 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.
Steve Anton845bb732017-12-05 20:50:2669 virtual std::string server_url() const;
henrike@webrtc.org28e20752013-07-10 00:45:3670 // 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.
deadbeef8d60a942017-02-27 22:47:3375// Returns null if the sdp string can't be parsed.
76// |error| may be null.
Mirko Bonadei3b56ee72018-10-15 15:15:1277RTC_EXPORT IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
78 int sdp_mline_index,
79 const std::string& sdp,
80 SdpParseError* error);
henrike@webrtc.org28e20752013-07-10 00:45:3681
Steve Anton27ab0e52018-07-23 22:11:5382// Creates an IceCandidateInterface based on a parsed candidate structure.
Mirko Bonadei3b56ee72018-10-15 15:15:1283RTC_EXPORT std::unique_ptr<IceCandidateInterface> CreateIceCandidate(
Steve Anton27ab0e52018-07-23 22:11:5384 const std::string& sdp_mid,
85 int sdp_mline_index,
86 const cricket::Candidate& candidate);
87
deadbeefb10f32f2017-02-08 09:38:2188// This class represents a collection of candidates for a specific m= section.
89// Used in SessionDescriptionInterface.
henrike@webrtc.org28e20752013-07-10 00:45:3690class IceCandidateCollection {
91 public:
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
Steve Anton88f2cb92017-12-05 20:47:3299// 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
102enum 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 offer-
107 // answer exchange must be considered complete after receiving this.
108};
109
110// Returns the string form of the given SDP type. String forms are defined in
111// SessionDescriptionInterface.
112const char* SdpTypeToString(SdpType type);
113
114// Returns the SdpType from its string form. The string form can be one of the
115// constants defined in SessionDescriptionInterface. Passing in any other string
116// results in nullopt.
Danil Chapovalov0bc58cf2018-06-21 11:32:56117absl::optional<SdpType> SdpTypeFromString(const std::string& type_str);
Steve Anton88f2cb92017-12-05 20:47:32118
deadbeefb10f32f2017-02-08 09:38:21119// Class representation of an SDP session description.
120//
121// An instance of this interface is supposed to be owned by one class at a time
122// and is therefore not expected to be thread safe.
123//
124// An instance can be created by CreateSessionDescription.
Mirko Bonadei3b56ee72018-10-15 15:15:12125class RTC_EXPORT SessionDescriptionInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36126 public:
Steve Anton88f2cb92017-12-05 20:47:32127 // String representations of the supported SDP types.
henrike@webrtc.org28e20752013-07-10 00:45:36128 static const char kOffer[];
129 static const char kPrAnswer[];
130 static const char kAnswer[];
131
132 virtual ~SessionDescriptionInterface() {}
deadbeefb10f32f2017-02-08 09:38:21133
134 // Only for use internally.
henrike@webrtc.org28e20752013-07-10 00:45:36135 virtual cricket::SessionDescription* description() = 0;
136 virtual const cricket::SessionDescription* description() const = 0;
deadbeefb10f32f2017-02-08 09:38:21137
henrike@webrtc.org28e20752013-07-10 00:45:36138 // Get the session id and session version, which are defined based on
139 // RFC 4566 for the SDP o= line.
140 virtual std::string session_id() const = 0;
141 virtual std::string session_version() const = 0;
deadbeefb10f32f2017-02-08 09:38:21142
Steve Anton88f2cb92017-12-05 20:47:32143 // Returns the type of this session description as an SdpType. Descriptions of
144 // the various types are found in the SdpType documentation.
145 // TODO(steveanton): Remove default implementation once Chromium has been
146 // updated.
147 virtual SdpType GetType() const;
148
deadbeefb10f32f2017-02-08 09:38:21149 // kOffer/kPrAnswer/kAnswer
Steve Anton88f2cb92017-12-05 20:47:32150 // TODO(steveanton): Remove this in favor of |GetType| that returns SdpType.
henrike@webrtc.org28e20752013-07-10 00:45:36151 virtual std::string type() const = 0;
deadbeefb10f32f2017-02-08 09:38:21152
henrike@webrtc.org28e20752013-07-10 00:45:36153 // Adds the specified candidate to the description.
deadbeefb10f32f2017-02-08 09:38:21154 //
henrike@webrtc.org28e20752013-07-10 00:45:36155 // Ownership is not transferred.
deadbeefb10f32f2017-02-08 09:38:21156 //
157 // Returns false if the session description does not have a media section
158 // that corresponds to |candidate.sdp_mid()| or
159 // |candidate.sdp_mline_index()|.
henrike@webrtc.org28e20752013-07-10 00:45:36160 virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0;
deadbeefb10f32f2017-02-08 09:38:21161
162 // Removes the candidates from the description, if found.
163 //
Honghai Zhang7fb69db2016-03-14 18:59:18164 // Returns the number of candidates removed.
165 virtual size_t RemoveCandidates(
Steve Anton845bb732017-12-05 20:50:26166 const std::vector<cricket::Candidate>& candidates);
Honghai Zhang7fb69db2016-03-14 18:59:18167
deadbeefb10f32f2017-02-08 09:38:21168 // Returns the number of m= sections in the session description.
henrike@webrtc.org28e20752013-07-10 00:45:36169 virtual size_t number_of_mediasections() const = 0;
deadbeefb10f32f2017-02-08 09:38:21170
171 // Returns a collection of all candidates that belong to a certain m=
172 // section.
henrike@webrtc.org28e20752013-07-10 00:45:36173 virtual const IceCandidateCollection* candidates(
174 size_t mediasection_index) const = 0;
deadbeefb10f32f2017-02-08 09:38:21175
henrike@webrtc.org28e20752013-07-10 00:45:36176 // Serializes the description to SDP.
177 virtual bool ToString(std::string* out) const = 0;
178};
179
deadbeefb10f32f2017-02-08 09:38:21180// Creates a SessionDescriptionInterface based on the SDP string and the type.
deadbeef8d60a942017-02-27 22:47:33181// Returns null if the sdp string can't be parsed or the type is unsupported.
182// |error| may be null.
Steve Anton88f2cb92017-12-05 20:47:32183// TODO(steveanton): This function is deprecated. Please use the functions below
184// which take an SdpType enum instead. Remove this once it is no longer used.
Mirko Bonadei3b56ee72018-10-15 15:15:12185RTC_EXPORT SessionDescriptionInterface* CreateSessionDescription(
186 const std::string& type,
187 const std::string& sdp,
188 SdpParseError* error);
henrike@webrtc.org28e20752013-07-10 00:45:36189
Steve Anton88f2cb92017-12-05 20:47:32190// Creates a SessionDescriptionInterface based on the SDP string and the type.
191// Returns null if the SDP string cannot be parsed.
192// If using the signature with |error_out|, details of the parsing error may be
193// written to |error_out| if it is not null.
Mirko Bonadei3b56ee72018-10-15 15:15:12194RTC_EXPORT std::unique_ptr<SessionDescriptionInterface>
195CreateSessionDescription(SdpType type, const std::string& sdp);
196RTC_EXPORT std::unique_ptr<SessionDescriptionInterface>
197CreateSessionDescription(SdpType type,
198 const std::string& sdp,
199 SdpParseError* error_out);
Steve Anton88f2cb92017-12-05 20:47:32200
Steve Antond9e4a062018-07-25 01:23:33201// Creates a SessionDescriptionInterface based on a parsed SDP structure and the
202// given type, ID and version.
203std::unique_ptr<SessionDescriptionInterface> CreateSessionDescription(
204 SdpType type,
205 const std::string& session_id,
206 const std::string& session_version,
207 std::unique_ptr<cricket::SessionDescription> description);
208
deadbeefb10f32f2017-02-08 09:38:21209// CreateOffer and CreateAnswer callback interface.
Mirko Bonadeiac194142018-10-22 15:08:37210class RTC_EXPORT CreateSessionDescriptionObserver
211 : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36212 public:
deadbeefb10f32f2017-02-08 09:38:21213 // This callback transfers the ownership of the |desc|.
214 // TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion
215 // around ownership.
henrike@webrtc.org28e20752013-07-10 00:45:36216 virtual void OnSuccess(SessionDescriptionInterface* desc) = 0;
Harald Alvestrand5081c0c2018-03-09 14:18:03217 // The OnFailure callback takes an RTCError, which consists of an
218 // error code and a string.
219 // RTCError is non-copyable, so it must be passed using std::move.
220 // Earlier versions of the API used a string argument. This version
221 // is deprecated; in order to let clients remove the old version, it has a
222 // default implementation. If both versions are unimplemented, the
223 // result will be a runtime error (stack overflow). This is intentional.
Mirko Bonadei79eb4dd2018-07-19 08:39:30224 virtual void OnFailure(RTCError error);
225 virtual void OnFailure(const std::string& error);
henrike@webrtc.org28e20752013-07-10 00:45:36226
227 protected:
Steve Anton845bb732017-12-05 20:50:26228 ~CreateSessionDescriptionObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36229};
230
deadbeefb10f32f2017-02-08 09:38:21231// SetLocalDescription and SetRemoteDescription callback interface.
Mirko Bonadeiac194142018-10-22 15:08:37232class RTC_EXPORT SetSessionDescriptionObserver : public rtc::RefCountInterface {
henrike@webrtc.org28e20752013-07-10 00:45:36233 public:
234 virtual void OnSuccess() = 0;
Harald Alvestrand5081c0c2018-03-09 14:18:03235 // See description in CreateSessionDescriptionObserver for OnFailure.
Mirko Bonadei79eb4dd2018-07-19 08:39:30236 virtual void OnFailure(RTCError error);
237
238 virtual void OnFailure(const std::string& error);
henrike@webrtc.org28e20752013-07-10 00:45:36239
240 protected:
Steve Anton845bb732017-12-05 20:50:26241 ~SetSessionDescriptionObserver() override = default;
henrike@webrtc.org28e20752013-07-10 00:45:36242};
243
244} // namespace webrtc
245
Mirko Bonadei92ea95e2017-09-15 04:47:31246#endif // API_JSEP_H_