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 {
  63    public:
  64     virtual ~TrackListener() = default;
  65
  66     /**
  67      * Called when the DOMMediaStream has a live track added, either by
  68      * script (addTrack()) or the source creating one.
  69      */
  70     virtual void NotifyTrackAdded(const RefPtr<MediaStreamTrack>& aTrack){};
  71
  72     /**
  73      * Called when the DOMMediaStream removes a live track from playback, either
  74      * by script (removeTrack(), track.stop()) or the source ending it.
  75      */
  76     virtual void NotifyTrackRemoved(const RefPtr<MediaStreamTrack>& aTrack){};
  77
  78     /**
  79      * Called when the DOMMediaStream has become active.
  80      */
  81     virtual void NotifyActive(){};
  82
  83     /**
  84      * Called when the DOMMediaStream has become inactive.
  85      */
  86     virtual void NotifyInactive(){};
  87
  88     /**
  89      * Called when the DOMMediaStream has become audible.
  90      */
  91     virtual void NotifyAudible(){};
  92
  93     /**
  94      * Called when the DOMMediaStream has become inaudible.
  95      */
  96     virtual void NotifyInaudible(){};
  97   };
  98
  99   explicit DOMMediaStream(nsPIDOMWindowInner* aWindow);
 100
 101   NS_DECL_ISUPPORTS_INHERITED
 102   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(DOMMediaStream, DOMEventTargetHelper)
 103   NS_DECLARE_STATIC_IID_ACCESSOR(NS_DOMMEDIASTREAM_IID)
 104
 105   virtual JSObject* WrapObject(JSContext* aCx,
 106                                JS::Handle<JSObject*> aGivenProto) override;
 107
 108   // WebIDL
 109
 110   static already_AddRefed<DOMMediaStream> Constructor(
 111       const dom::GlobalObject& aGlobal, ErrorResult& aRv);
 112
 113   static already_AddRefed<DOMMediaStream> Constructor(
 114       const dom::GlobalObject& aGlobal, const DOMMediaStream& aStream,
 115       ErrorResult& aRv);
 116
 117   static already_AddRefed<DOMMediaStream> Constructor(
 118       const dom::GlobalObject& aGlobal,
 119       const dom::Sequence<OwningNonNull<MediaStreamTrack>>& aTracks,
 120       ErrorResult& aRv);
 121
 122   static already_AddRefed<dom::Promise> CountUnderlyingStreams(
 123       const dom::GlobalObject& aGlobal, ErrorResult& aRv);
 124
 125   void GetId(nsAString& aID) const;
 126
 127   void GetAudioTracks(nsTArray<RefPtr<AudioStreamTrack>>& aTracks) const;
 128   void GetAudioTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 129   void GetVideoTracks(nsTArray<RefPtr<VideoStreamTrack>>& aTracks) const;
 130   void GetVideoTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 131   void GetTracks(nsTArray<RefPtr<MediaStreamTrack>>& aTracks) const;
 132   MediaStreamTrack* GetTrackById(const nsAString& aId) const;
 133   void AddTrack(MediaStreamTrack& aTrack);
 134   void RemoveTrack(MediaStreamTrack& aTrack);
 135   already_AddRefed<DOMMediaStream> Clone();
 136
 137   bool Active() const;
 138
 139   IMPL_EVENT_HANDLER(addtrack)
 140   IMPL_EVENT_HANDLER(removetrack)
 141
 142   // NON-WebIDL
 143
 144   // Returns true if this stream contains a live audio track.
 145   bool Audible() const;
 146
 147   /**
 148    * Returns true if this DOMMediaStream has aTrack in mTracks.
 149    */
 150   bool HasTrack(const MediaStreamTrack& aTrack) const;
 151
 152   /**
 153    * Returns a principal indicating who may access this stream. The stream
 154    * contents can only be accessed by principals subsuming this principal.
 155    */
 156   already_AddRefed<nsIPrincipal> GetPrincipal();
 157
 158   // Webrtc allows the remote side to name a stream whatever it wants, and we
 159   // need to surface this to content.
 160   void AssignId(const nsAString& aID) { mID = aID; }
 161
 162   /**
 163    * Adds a MediaStreamTrack to mTracks and raises "addtrack".
 164    *
 165    * Note that "addtrack" is raised synchronously and only has an effect if
 166    * this MediaStream is already exposed to script. For spec compliance this is
 167    * to be called from an async task.
 168    */
 169   void AddTrackInternal(MediaStreamTrack* aTrack);
 170
 171   /**
 172    * Removes a MediaStreamTrack from mTracks and fires "removetrack" if it
 173    * was removed.
 174    *
 175    * Note that "removetrack" is raised synchronously and only has an effect if
 176    * this MediaStream is already exposed to script. For spec compliance this is
 177    * to be called from an async task.
 178    */
 179   void RemoveTrackInternal(MediaStreamTrack* aTrack);
 180
 181   /**
 182    * Add an nsISupports object that this stream will keep alive as long as
 183    * the stream itself is alive.
 184    */
 185   void AddConsumerToKeepAlive(nsISupports* aConsumer) {
 186     mConsumersToKeepAlive.AppendElement(aConsumer);
 187   }
 188
 189   // Registers a track listener to this MediaStream, for listening to changes
 190   // to our track set. The caller must call UnregisterTrackListener before
 191   // being destroyed, so we don't hold on to a dead pointer. Main thread only.
 192   void RegisterTrackListener(TrackListener* aListener);
 193
 194   // Unregisters a track listener from this MediaStream. The caller must call
 195   // UnregisterTrackListener before being destroyed, so we don't hold on to
 196   // a dead pointer. Main thread only.
 197   void UnregisterTrackListener(TrackListener* aListener);
 198
 199  protected:
 200   virtual ~DOMMediaStream();
 201
 202   void Destroy();
 203
 204   // Dispatches NotifyActive() to all registered track listeners.
 205   void NotifyActive();
 206
 207   // Dispatches NotifyInactive() to all registered track listeners.
 208   void NotifyInactive();
 209
 210   // Dispatches NotifyAudible() to all registered track listeners.
 211   void NotifyAudible();
 212
 213   // Dispatches NotifyInaudible() to all registered track listeners.
 214   void NotifyInaudible();
 215
 216   // Dispatches NotifyTrackAdded() to all registered track listeners.
 217   void NotifyTrackAdded(const RefPtr<MediaStreamTrack>& aTrack);
 218
 219   // Dispatches NotifyTrackRemoved() to all registered track listeners.
 220   void NotifyTrackRemoved(const RefPtr<MediaStreamTrack>& aTrack);
 221
 222   // Dispatches "addtrack" or "removetrack".
 223   nsresult DispatchTrackEvent(const nsAString& aName,
 224                               const RefPtr<MediaStreamTrack>& aTrack);
 225
 226   // MediaStreamTracks contained by this DOMMediaStream.
 227   nsTArray<RefPtr<MediaStreamTrack>> mTracks;
 228
 229   // Listener tracking when live MediaStreamTracks in mTracks end.
 230   class PlaybackTrackListener;
 231   RefPtr<PlaybackTrackListener> mPlaybackTrackListener;
 232
 233   nsString mID;
 234
 235   // Keep these alive while the stream is alive.
 236   nsTArray<nsCOMPtr<nsISupports>> mConsumersToKeepAlive;
 237
 238   // The track listeners subscribe to changes in this stream's track set.
 239   nsTArray<TrackListener*> mTrackListeners;
 240
 241   // True if this stream has live tracks.
 242   bool mActive = false;
 243
 244   // True if this stream has live audio tracks.
 245   bool mAudible = false;
 246 };
 247
 248 NS_DEFINE_STATIC_IID_ACCESSOR(DOMMediaStream, NS_DOMMEDIASTREAM_IID)
 249
 250 }  // namespace mozilla
 251
 252 #endif /* NSDOMMEDIASTREAM_H_ */