src/third_party/libjingle/source/talk/session/media/mediamessages.h

   1 /*
   2  * libjingle
   3  * Copyright 2010 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 /*
  29  * A collection of functions and types for serializing and
  30  * deserializing Jingle session messages related to media.
  31  * Specificially, the <notify> and <view> messages.  They are not yet
  32  * standardized, but their current documentation can be found at:
  33  * goto/jinglemuc
  34  */
  35
  36 #ifndef TALK_SESSION_MEDIA_MEDIAMESSAGES_H_
  37 #define TALK_SESSION_MEDIA_MEDIAMESSAGES_H_
  38
  39 #include <string>
  40 #include <vector>
  41
  42 #include "talk/media/base/mediachannel.h"  // For RtpHeaderExtension
  43 #include "talk/media/base/streamparams.h"
  44 #include "webrtc/p2p/base/parsing.h"
  45 #include "webrtc/p2p/base/sessiondescription.h"
  46 #include "webrtc/base/basictypes.h"
  47
  48 namespace cricket {
  49
  50 // A collection of audio and video and data streams. Most of the
  51 // methods are merely for convenience. Many of these methods are keyed
  52 // by ssrc, which is the source identifier in the RTP spec
  53 // (http://tools.ietf.org/html/rfc3550).
  54 struct MediaStreams {
  55  public:
  56   MediaStreams() {}
  57   void CopyFrom(const MediaStreams& sources);
  58
  59   bool empty() const {
  60     return audio_.empty() && video_.empty() && data_.empty();
  61   }
  62
  63   std::vector<StreamParams>* mutable_audio() { return &audio_; }
  64   std::vector<StreamParams>* mutable_video() { return &video_; }
  65   std::vector<StreamParams>* mutable_data() { return &data_; }
  66   const std::vector<StreamParams>& audio() const { return audio_; }
  67   const std::vector<StreamParams>& video() const { return video_; }
  68   const std::vector<StreamParams>& data() const { return data_; }
  69
  70   // Gets a stream, returning true if found.
  71   bool GetAudioStream(
  72       const StreamSelector& selector, StreamParams* stream);
  73   bool GetVideoStream(
  74       const StreamSelector& selector, StreamParams* stream);
  75   bool GetDataStream(
  76       const StreamSelector& selector, StreamParams* stream);
  77   // Adds a stream.
  78   void AddAudioStream(const StreamParams& stream);
  79   void AddVideoStream(const StreamParams& stream);
  80   void AddDataStream(const StreamParams& stream);
  81   // Removes a stream, returning true if found and removed.
  82   bool RemoveAudioStream(const StreamSelector& selector);
  83   bool RemoveVideoStream(const StreamSelector& selector);
  84   bool RemoveDataStream(const StreamSelector& selector);
  85
  86  private:
  87   std::vector<StreamParams> audio_;
  88   std::vector<StreamParams> video_;
  89   std::vector<StreamParams> data_;
  90
  91   DISALLOW_COPY_AND_ASSIGN(MediaStreams);
  92 };
  93
  94 // In a <view> message, there are a number of views specified.  This
  95 // represents one such view.  We currently only support "static"
  96 // views.
  97 struct StaticVideoView {
  98   StaticVideoView(const StreamSelector& selector,
  99                   int width, int height, int framerate)
 100       : selector(selector),
 101         width(width),
 102         height(height),
 103         framerate(framerate),
 104         preference(0) {
 105   }
 106
 107   StreamSelector selector;
 108   int width;
 109   int height;
 110   int framerate;
 111   int preference;
 112 };
 113
 114 typedef std::vector<StaticVideoView> StaticVideoViews;
 115
 116 // Represents a whole view request message, which contains many views.
 117 struct ViewRequest {
 118   StaticVideoViews static_video_views;
 119 };
 120
 121 // If the parent element (usually <jingle>) is a jingle view.
 122 bool IsJingleViewRequest(const buzz::XmlElement* action_elem);
 123
 124 // Parses a view request from the parent element (usually
 125 // <jingle>). If it fails, it returns false and fills an error
 126 // message.
 127 bool ParseJingleViewRequest(const buzz::XmlElement* action_elem,
 128                             ViewRequest* view_request,
 129                             ParseError* error);
 130
 131 // Serializes a view request to XML.  If it fails, returns false and
 132 // fills in an error message.
 133 bool WriteJingleViewRequest(const std::string& content_name,
 134                             const ViewRequest& view,
 135                             XmlElements* elems,
 136                             WriteError* error);
 137
 138 // TODO(pthatcher): Get rid of legacy source notify and replace with
 139 // description-info as soon as reflector is capable of sending it.
 140 bool IsSourcesNotify(const buzz::XmlElement* action_elem);
 141
 142 // If the given elem has <streams>.
 143 bool HasJingleStreams(const buzz::XmlElement* desc_elem);
 144
 145 // Parses streams from a jingle <description>.  If it fails, returns
 146 // false and fills an error message.
 147 bool ParseJingleStreams(const buzz::XmlElement* desc_elem,
 148                         std::vector<StreamParams>* streams,
 149                         ParseError* error);
 150
 151 // Write a <streams> element to the parent_elem.
 152 void WriteJingleStreams(const std::vector<StreamParams>& streams,
 153                         buzz::XmlElement* parent_elem);
 154
 155 // Parses rtp header extensions from a jingle <description>.  If it
 156 // fails, returns false and fills an error message.
 157 bool ParseJingleRtpHeaderExtensions(
 158     const buzz::XmlElement* desc_elem,
 159     std::vector<RtpHeaderExtension>* hdrexts,
 160     ParseError* error);
 161
 162 // Writes <rtp-hdrext> elements to the parent_elem.
 163 void WriteJingleRtpHeaderExtensions(
 164     const std::vector<RtpHeaderExtension>& hdrexts,
 165     buzz::XmlElement* parent_elem);
 166
 167 }  // namespace cricket
 168
 169 #endif  // TALK_SESSION_MEDIA_MEDIAMESSAGES_H_