254 lines
9.7 KiB
C
254 lines
9.7 KiB
C
|
/*
|
||
|
|
* Copyright 2012 The WebRTC project authors. All Rights Reserved.
|
||
|
|
*
|
||
|
|
* Use of this source code is governed by a BSD-style license
|
||
|
|
* that can be found in the LICENSE file in the root of the source
|
||
|
|
* tree. An additional intellectual property rights grant can be found
|
||
|
|
* in the file PATENTS. All contributing project authors may
|
||
|
|
* be found in the AUTHORS file in the root of the source tree.
|
||
|
|
*/
|
||
|
|
|
||
|
|
// This file contains declarations of interfaces that wrap SDP-related
|
||
|
|
// constructs; session descriptions and ICE candidates. The inner "cricket::"
|
||
|
|
// objects shouldn't be accessed directly; the intention is that an application
|
||
|
|
// using the PeerConnection API only creates these objects from strings, and
|
||
|
|
// them passes them into the PeerConnection.
|
||
|
|
//
|
||
|
|
// Though in the future, we're planning to provide an SDP parsing API, with a
|
||
|
|
// structure more friendly than cricket::SessionDescription.
|
||
|
|
|
||
|
|
#ifndef API_JSEP_H_
|
||
|
|
#define API_JSEP_H_
|
||
|
|
|
||
|
|
#include <stddef.h>
|
||
|
|
|
||
|
|
#include <memory>
|
||
|
|
#include <string>
|
||
|
|
#include <vector>
|
||
|
|
|
||
|
|
#include "absl/types/optional.h"
|
||
|
|
#include "api/rtc_error.h"
|
||
|
|
#include "rtc_base/ref_count.h"
|
||
|
|
#include "rtc_base/system/rtc_export.h"
|
||
|
|
|
||
|
|
namespace cricket {
|
||
|
|
class Candidate;
|
||
|
|
class SessionDescription;
|
||
|
|
} // namespace cricket
|
||
|
|
|
||
|
|
namespace webrtc {
|
||
|
|
|
||
|
|
struct SdpParseError {
|
||
|
|
public:
|
||
|
|
// The sdp line that causes the error.
|
||
|
|
std::string line;
|
||
|
|
// Explains the error.
|
||
|
|
std::string description;
|
||
|
|
};
|
||
|
|
|
||
|
|
// Class representation of an ICE candidate.
|
||
|
|
//
|
||
|
|
// An instance of this interface is supposed to be owned by one class at
|
||
|
|
// a time and is therefore not expected to be thread safe.
|
||
|
|
//
|
||
|
|
// An instance can be created by CreateIceCandidate.
|
||
|
|
class RTC_EXPORT IceCandidateInterface {
|
||
|
|
public:
|
||
|
|
virtual ~IceCandidateInterface() {}
|
||
|
|
// If present, this is the value of the "a=mid" attribute of the candidate's
|
||
|
|
// m= section in SDP, which identifies the m= section.
|
||
|
|
virtual std::string sdp_mid() const = 0;
|
||
|
|
// This indicates the index (starting at zero) of m= section this candidate
|
||
|
|
// is associated with. Needed when an endpoint doesn't support MIDs.
|
||
|
|
virtual int sdp_mline_index() const = 0;
|
||
|
|
// Only for use internally.
|
||
|
|
virtual const cricket::Candidate& candidate() const = 0;
|
||
|
|
// The URL of the ICE server which this candidate was gathered from.
|
||
|
|
// TODO(zhihuang): Remove the default implementation once the subclasses
|
||
|
|
// implement this method.
|
||
|
|
virtual std::string server_url() const;
|
||
|
|
// Creates a SDP-ized form of this candidate.
|
||
|
|
virtual bool ToString(std::string* out) const = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
// Creates a IceCandidateInterface based on SDP string.
|
||
|
|
// Returns null if the sdp string can't be parsed.
|
||
|
|
// |error| may be null.
|
||
|
|
RTC_EXPORT IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
|
||
|
|
int sdp_mline_index,
|
||
|
|
const std::string& sdp,
|
||
|
|
SdpParseError* error);
|
||
|
|
|
||
|
|
// Creates an IceCandidateInterface based on a parsed candidate structure.
|
||
|
|
RTC_EXPORT std::unique_ptr<IceCandidateInterface> CreateIceCandidate(
|
||
|
|
const std::string& sdp_mid,
|
||
|
|
int sdp_mline_index,
|
||
|
|
const cricket::Candidate& candidate);
|
||
|
|
|
||
|
|
// This class represents a collection of candidates for a specific m= section.
|
||
|
|
// Used in SessionDescriptionInterface.
|
||
|
|
class IceCandidateCollection {
|
||
|
|
public:
|
||
|
|
virtual ~IceCandidateCollection() {}
|
||
|
|
virtual size_t count() const = 0;
|
||
|
|
// Returns true if an equivalent |candidate| exist in the collection.
|
||
|
|
virtual bool HasCandidate(const IceCandidateInterface* candidate) const = 0;
|
||
|
|
virtual const IceCandidateInterface* at(size_t index) const = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
// Enum that describes the type of the SessionDescriptionInterface.
|
||
|
|
// Corresponds to RTCSdpType in the WebRTC specification.
|
||
|
|
// https://w3c.github.io/webrtc-pc/#dom-rtcsdptype
|
||
|
|
enum class SdpType {
|
||
|
|
kOffer, // Description must be treated as an SDP offer.
|
||
|
|
kPrAnswer, // Description must be treated as an SDP answer, but not a final
|
||
|
|
// answer.
|
||
|
|
kAnswer, // Description must be treated as an SDP final answer, and the
|
||
|
|
// offer-answer exchange must be considered complete after
|
||
|
|
// receiving this.
|
||
|
|
kRollback // Resets any pending offers and sets signaling state back to
|
||
|
|
// stable.
|
||
|
|
};
|
||
|
|
|
||
|
|
// Returns the string form of the given SDP type. String forms are defined in
|
||
|
|
// SessionDescriptionInterface.
|
||
|
|
RTC_EXPORT const char* SdpTypeToString(SdpType type);
|
||
|
|
|
||
|
|
// Returns the SdpType from its string form. The string form can be one of the
|
||
|
|
// constants defined in SessionDescriptionInterface. Passing in any other string
|
||
|
|
// results in nullopt.
|
||
|
|
absl::optional<SdpType> SdpTypeFromString(const std::string& type_str);
|
||
|
|
|
||
|
|
// Class representation of an SDP session description.
|
||
|
|
//
|
||
|
|
// An instance of this interface is supposed to be owned by one class at a time
|
||
|
|
// and is therefore not expected to be thread safe.
|
||
|
|
//
|
||
|
|
// An instance can be created by CreateSessionDescription.
|
||
|
|
class RTC_EXPORT SessionDescriptionInterface {
|
||
|
|
public:
|
||
|
|
// String representations of the supported SDP types.
|
||
|
|
static const char kOffer[];
|
||
|
|
static const char kPrAnswer[];
|
||
|
|
static const char kAnswer[];
|
||
|
|
static const char kRollback[];
|
||
|
|
|
||
|
|
virtual ~SessionDescriptionInterface() {}
|
||
|
|
|
||
|
|
// Create a new SessionDescriptionInterface object
|
||
|
|
// with the same values as the old object.
|
||
|
|
// TODO(bugs.webrtc.org:12215): Remove default implementation
|
||
|
|
virtual std::unique_ptr<SessionDescriptionInterface> Clone() const {
|
||
|
|
return nullptr;
|
||
|
|
}
|
||
|
|
|
||
|
|
// Only for use internally.
|
||
|
|
virtual cricket::SessionDescription* description() = 0;
|
||
|
|
virtual const cricket::SessionDescription* description() const = 0;
|
||
|
|
|
||
|
|
// Get the session id and session version, which are defined based on
|
||
|
|
// RFC 4566 for the SDP o= line.
|
||
|
|
virtual std::string session_id() const = 0;
|
||
|
|
virtual std::string session_version() const = 0;
|
||
|
|
|
||
|
|
// Returns the type of this session description as an SdpType. Descriptions of
|
||
|
|
// the various types are found in the SdpType documentation.
|
||
|
|
// TODO(steveanton): Remove default implementation once Chromium has been
|
||
|
|
// updated.
|
||
|
|
virtual SdpType GetType() const;
|
||
|
|
|
||
|
|
// kOffer/kPrAnswer/kAnswer
|
||
|
|
// TODO(steveanton): Remove this in favor of |GetType| that returns SdpType.
|
||
|
|
virtual std::string type() const = 0;
|
||
|
|
|
||
|
|
// Adds the specified candidate to the description.
|
||
|
|
//
|
||
|
|
// Ownership is not transferred.
|
||
|
|
//
|
||
|
|
// Returns false if the session description does not have a media section
|
||
|
|
// that corresponds to |candidate.sdp_mid()| or
|
||
|
|
// |candidate.sdp_mline_index()|.
|
||
|
|
virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0;
|
||
|
|
|
||
|
|
// Removes the candidates from the description, if found.
|
||
|
|
//
|
||
|
|
// Returns the number of candidates removed.
|
||
|
|
virtual size_t RemoveCandidates(
|
||
|
|
const std::vector<cricket::Candidate>& candidates);
|
||
|
|
|
||
|
|
// Returns the number of m= sections in the session description.
|
||
|
|
virtual size_t number_of_mediasections() const = 0;
|
||
|
|
|
||
|
|
// Returns a collection of all candidates that belong to a certain m=
|
||
|
|
// section.
|
||
|
|
virtual const IceCandidateCollection* candidates(
|
||
|
|
size_t mediasection_index) const = 0;
|
||
|
|
|
||
|
|
// Serializes the description to SDP.
|
||
|
|
virtual bool ToString(std::string* out) const = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
// Creates a SessionDescriptionInterface based on the SDP string and the type.
|
||
|
|
// Returns null if the sdp string can't be parsed or the type is unsupported.
|
||
|
|
// |error| may be null.
|
||
|
|
// TODO(steveanton): This function is deprecated. Please use the functions below
|
||
|
|
// which take an SdpType enum instead. Remove this once it is no longer used.
|
||
|
|
RTC_EXPORT SessionDescriptionInterface* CreateSessionDescription(
|
||
|
|
const std::string& type,
|
||
|
|
const std::string& sdp,
|
||
|
|
SdpParseError* error);
|
||
|
|
|
||
|
|
// Creates a SessionDescriptionInterface based on the SDP string and the type.
|
||
|
|
// Returns null if the SDP string cannot be parsed.
|
||
|
|
// If using the signature with |error_out|, details of the parsing error may be
|
||
|
|
// written to |error_out| if it is not null.
|
||
|
|
RTC_EXPORT std::unique_ptr<SessionDescriptionInterface>
|
||
|
|
CreateSessionDescription(SdpType type, const std::string& sdp);
|
||
|
|
RTC_EXPORT std::unique_ptr<SessionDescriptionInterface>
|
||
|
|
CreateSessionDescription(SdpType type,
|
||
|
|
const std::string& sdp,
|
||
|
|
SdpParseError* error_out);
|
||
|
|
|
||
|
|
// Creates a SessionDescriptionInterface based on a parsed SDP structure and the
|
||
|
|
// given type, ID and version.
|
||
|
|
std::unique_ptr<SessionDescriptionInterface> CreateSessionDescription(
|
||
|
|
SdpType type,
|
||
|
|
const std::string& session_id,
|
||
|
|
const std::string& session_version,
|
||
|
|
std::unique_ptr<cricket::SessionDescription> description);
|
||
|
|
|
||
|
|
// CreateOffer and CreateAnswer callback interface.
|
||
|
|
class RTC_EXPORT CreateSessionDescriptionObserver
|
||
|
|
: public rtc::RefCountInterface {
|
||
|
|
public:
|
||
|
|
// This callback transfers the ownership of the |desc|.
|
||
|
|
// TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion
|
||
|
|
// around ownership.
|
||
|
|
virtual void OnSuccess(SessionDescriptionInterface* desc) = 0;
|
||
|
|
// The OnFailure callback takes an RTCError, which consists of an
|
||
|
|
// error code and a string.
|
||
|
|
// RTCError is non-copyable, so it must be passed using std::move.
|
||
|
|
// Earlier versions of the API used a string argument. This version
|
||
|
|
// is removed; its functionality was the same as passing
|
||
|
|
// error.message.
|
||
|
|
virtual void OnFailure(RTCError error) = 0;
|
||
|
|
|
||
|
|
protected:
|
||
|
|
~CreateSessionDescriptionObserver() override = default;
|
||
|
|
};
|
||
|
|
|
||
|
|
// SetLocalDescription and SetRemoteDescription callback interface.
|
||
|
|
class RTC_EXPORT SetSessionDescriptionObserver : public rtc::RefCountInterface {
|
||
|
|
public:
|
||
|
|
virtual void OnSuccess() = 0;
|
||
|
|
// See description in CreateSessionDescriptionObserver for OnFailure.
|
||
|
|
virtual void OnFailure(RTCError error) = 0;
|
||
|
|
|
||
|
|
protected:
|
||
|
|
~SetSessionDescriptionObserver() override = default;
|
||
|
|
};
|
||
|
|
|
||
|
|
} // namespace webrtc
|
||
|
|
|
||
|
|
#endif // API_JSEP_H_
|