dom/media/DOMMediaStream.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-*/
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef NSDOMMEDIASTREAM_H_
   7 #define NSDOMMEDIASTREAM_H_
   8
   9 #include "ImageContainer.h"
  10
  11 #include "nsCycleCollectionParticipant.h"
  12 #include "nsWrapperCache.h"
  13 #include "nsIPrincipal.h"
  14 #include "MediaTrackConstraints.h"
  15 #include "mozilla/DOMEventTargetHelper.h"
  16 #include "mozilla/RelativeTimeline.h"
  17 #include "mozilla/WeakPtr.h"
  18
  19 namespace mozilla {
  20
  21 class AbstractThread;
  22 class DOMMediaStream;
  23
  24 enum class BlockingMode;
  25
  26 namespace dom {
  27 class HTMLCanvasElement;
  28 class MediaStreamTrack;
  29 class MediaStreamTrackSource;
  30 class AudioStreamTrack;
  31 class VideoStreamTrack;
  32 }  // namespace dom
  33
  34 namespace layers {
  35 class ImageContainer;
  36 class OverlayImage;
  37 }  // namespace layers
  38
  39 #define NS_DOMMEDIASTREAM_IID                        \
  40   {                                                  \
  41     0x8cb65468, 0x66c0, 0x444e, {                    \
  42       0x89, 0x9f, 0x89, 0x1d, 0x9e, 0xd2, 0xbe, 0x7c \
  43     }                                                \
  44   }
  45
  46 /**
  47  * DOMMediaStream is the implementation of the js-exposed MediaStream interface.
  48  *
  49  * This is a thin main-thread class grouping MediaStreamTracks together.
  50  */
  51 class DOMMediaStream : public DOMEventTargetHelper,
  52                        public RelativeTimeline,
  53                        public SupportsWeakPtr {
  54   typedef dom::MediaStreamTrack MediaStreamTrack;
  55   typedef dom::AudioStreamTrack AudioStreamTrack;
  56   typedef dom::VideoStreamTrack VideoStreamTrack;
  57   typedef dom::MediaStreamTrackSource MediaStreamTrackSource;
  58
  59  public:
  60   typedef dom::MediaTrackConstraints MediaTrackConstraints;
  61
  62   class TrackListener : public nsISupports {
  63    public:
  64     NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  65     NS_DECL_CYCLE_COLLECTION_CLASS(TrackListener)
  66
  67     /**
  68      * Called when the DOMMediaStream has a live track added, either by
  69      * script (addTrack()) or the source creating one.
  70      */
  71     virtual void NotifyTrackAdded(const RefPtr<MediaStreamTrack>& aTrack){};
  72
  73     /**
  74      * Called when the DOMMediaStream removes a live track from playback, either
  75      * by script (removeTrack(), track.stop()) or the source ending it.
  76      */
  77     virtual void NotifyTrackRemoved(const RefPtr<MediaStreamTrack>& aTrack){};
  78
  79     /**
  80      * Called when the DOMMediaStream has become active.
  81      */
  82     virtual void NotifyActive(){};
  83
  84     /**
  85      * Called when the DOMMediaStream has become inactive.
  86      */
  87     virtual void NotifyInactive(){};
  88
  89     /**
  90      * Called when the DOMMediaStream has become audible.
  91      */
  92     virtual void NotifyAudible(){};
  93
  94     /**
  95      * Called when the DOMMediaStream has become inaudible.
  96      */
  97     virtual void NotifyInaudible(){};
  98
  99    protected:
 100     virtual ~TrackListener() = default;
 101   };
 102
 103   explicit DOMMediaStream(nsPIDOMWindowInner* aWindow);
 104
 105   NS_DECL_ISUPPORTS_INHERITED
 106   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(DOMMediaStream, DOMEventTargetHelper)
 107   NS_DECLARE_STATIC_IID_ACCESSOR(NS_DOMMEDIASTREAM_IID)
 108
 109   virtual JSObject* WrapObject(JSContext* aCx,
 110                                JS::Handle<JSObject*> aGivenProto) override;
 111
 112   // WebIDL
 113
 114   static already_AddRefed<DOMMediaStream> Constructor(
 115       const dom::GlobalObject& aGlobal, ErrorResult& aRv);
 116
 117   static already_AddRefed<DOMMediaStream> Constructor(
 118       const dom::GlobalObject& aGlobal, const DOMMediaStream& aStream,
 119       ErrorResult& aRv);
 120
 121   static already_AddRefed<DOMMediaStream> Constructor(
 122       const dom::GlobalObject& aGlobal,
 123       const dom::Sequence<OwningNonNull<MediaStreamTrack>>& aTracks,
 124       ErrorResult& aRv);
 125
 126   static already_AddRefed<dom::Promise> CountUnderlyingStreams(
 127       const dom::GlobalObject& aGlobal, ErrorResult& aRv);
 128
 129   void GetId(nsAString& aID) const;
 130
 131   void GetAudioTracks(nsTArray<RefPtr<AudioStreamTrack>>& aTracks) const;
 132   void GetAudioTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 133   void GetVideoTracks(nsTArray<RefPtr<VideoStreamTrack>>& aTracks) const;
 134   void GetVideoTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 135   void GetTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 136   MediaStreamTrack* GetTrackById(const nsAString& aId) const;
 137   void AddTrack(MediaStreamTrack& aTrack);
 138   void RemoveTrack(MediaStreamTrack& aTrack);
 139   already_AddRefed<DOMMediaStream> Clone();
 140
 141   bool Active() const;
 142
 143   IMPL_EVENT_HANDLER(addtrack)
 144   IMPL_EVENT_HANDLER(removetrack)
 145
 146   // NON-WebIDL
 147
 148   // Returns true if this stream contains a live audio track.
 149   bool Audible() const;
 150
 151   /**
 152    * Returns true if this DOMMediaStream has aTrack in mTracks.
 153    */
 154   bool HasTrack(const MediaStreamTrack& aTrack) const;
 155
 156   /**
 157    * Returns a principal indicating who may access this stream. The stream
 158    * contents can only be accessed by principals subsuming this principal.
 159    */
 160   already_AddRefed<nsIPrincipal> GetPrincipal();
 161
 162   // Webrtc allows the remote side to name a stream whatever it wants, and we
 163   // need to surface this to content.
 164   void AssignId(const nsAString& aID) { mID = aID; }
 165
 166   /**
 167    * Adds a MediaStreamTrack to mTracks and raises "addtrack".
 168    *
 169    * Note that "addtrack" is raised synchronously and only has an effect if
 170    * this MediaStream is already exposed to script. For spec compliance this is
 171    * to be called from an async task.
 172    */
 173   void AddTrackInternal(MediaStreamTrack* aTrack);
 174
 175   /**
 176    * Removes a MediaStreamTrack from mTracks and fires "removetrack" if it
 177    * was removed.
 178    *
 179    * Note that "removetrack" is raised synchronously and only has an effect if
 180    * this MediaStream is already exposed to script. For spec compliance this is
 181    * to be called from an async task.
 182    */
 183   void RemoveTrackInternal(MediaStreamTrack* aTrack);
 184
 185   /**
 186    * Add an nsISupports object that this stream will keep alive as long as
 187    * the stream itself is alive.
 188    */
 189   void AddConsumerToKeepAlive(nsISupports* aConsumer) {
 190     mConsumersToKeepAlive.AppendElement(aConsumer);
 191   }
 192
 193   // Registers a track listener to this MediaStream, for listening to changes
 194   // to our track set. The caller must call UnregisterTrackListener before
 195   // being destroyed, so we don't hold on to a dead pointer. Main thread only.
 196   void RegisterTrackListener(TrackListener* aListener);
 197
 198   // Unregisters a track listener from this MediaStream. The caller must call
 199   // UnregisterTrackListener before being destroyed, so we don't hold on to
 200   // a dead pointer. Main thread only.
 201   void UnregisterTrackListener(TrackListener* aListener);
 202
 203  protected:
 204   virtual ~DOMMediaStream();
 205
 206   void Destroy();
 207
 208   // Dispatches NotifyActive() to all registered track listeners.
 209   void NotifyActive();
 210
 211   // Dispatches NotifyInactive() to all registered track listeners.
 212   void NotifyInactive();
 213
 214   // Dispatches NotifyAudible() to all registered track listeners.
 215   void NotifyAudible();
 216
 217   // Dispatches NotifyInaudible() to all registered track listeners.
 218   void NotifyInaudible();
 219
 220   // Dispatches NotifyTrackAdded() to all registered track listeners.
 221   void NotifyTrackAdded(const RefPtr<MediaStreamTrack>& aTrack);
 222
 223   // Dispatches NotifyTrackRemoved() to all registered track listeners.
 224   void NotifyTrackRemoved(const RefPtr<MediaStreamTrack>& aTrack);
 225
 226   // Dispatches "addtrack" or "removetrack".
 227   nsresult DispatchTrackEvent(const nsAString& aName,
 228                               const RefPtr<MediaStreamTrack>& aTrack);
 229
 230   // MediaStreamTracks contained by this DOMMediaStream.
 231   nsTArray<RefPtr<MediaStreamTrack>> mTracks;
 232
 233   // Listener tracking when live MediaStreamTracks in mTracks end.
 234   class PlaybackTrackListener;
 235   RefPtr<PlaybackTrackListener> mPlaybackTrackListener;
 236
 237   nsString mID;
 238
 239   // Keep these alive while the stream is alive.
 240   nsTArray<nsCOMPtr<nsISupports>> mConsumersToKeepAlive;
 241
 242   // The track listeners subscribe to changes in this stream's track set.
 243   nsTArray<RefPtr<TrackListener>> mTrackListeners;
 244
 245   // True if this stream has live tracks.
 246   bool mActive = false;
 247
 248   // True if this stream has live audio tracks.
 249   bool mAudible = false;
 250 };
 251
 252 NS_DEFINE_STATIC_IID_ACCESSOR(DOMMediaStream, NS_DOMMEDIASTREAM_IID)
 253
 254 }  // namespace mozilla
 255
 256 #endif /* NSDOMMEDIASTREAM_H_ */