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 "webrtc/base/basictypes.h"
37#include "webrtc/base/refcount.h"
38
39namespace cricket {
40class SessionDescription;
41class Candidate;
42}  // namespace cricket
43
44namespace webrtc {
45
46struct 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.
57class 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.
75IceCandidateInterface* 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.
80IceCandidateInterface* 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.
88class 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.
100class 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.
132SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
133                                                      const std::string& sdp);
134
135// |error| can be NULL if doesn't care about the failure reason.
136SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
137                                                      const std::string& sdp,
138                                                      SdpParseError* error);
139
140// Jsep CreateOffer and CreateAnswer callback interface.
141class CreateSessionDescriptionObserver : public rtc::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.
153class SetSessionDescriptionObserver : public rtc::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