content/media/video/public/nsMediaStream.h

   1 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla code.
  16  *
  17  * The Initial Developer of the Original Code is the Mozilla Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 2007
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *  Chris Double <chris.double@double.co.nz>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37 #if !defined(nsMediaStream_h_)
  38 #define nsMediaStream_h_
  39
  40 #include "nsCOMPtr.h"
  41 #include "nsAutoPtr.h"
  42 #include "nsIChannel.h"
  43 #include "nsIPrincipal.h"
  44 #include "nsIURI.h"
  45 #include "prlock.h"
  46
  47 class nsMediaDecoder;
  48
  49 // An abstract class that implements the low level functionality of nsMediaStream to open, close,
  50 // read and seek in streams. nsMediaStream constructs a concrete implementation of this class based
  51 // on the channel type to enable efficient seeking, reading and writing optimized for the channel type.
  52 class nsStreamStrategy
  53 {
  54 public:
  55  nsStreamStrategy(nsMediaDecoder* aDecoder, nsIChannel* aChannel, nsIURI* aURI) :
  56     mDecoder(aDecoder),
  57     mChannel(aChannel),
  58     mURI(aURI),
  59     mLock(nsnull)
  60   {
  61     MOZ_COUNT_CTOR(nsStreamStrategy);
  62     mLock = PR_NewLock();
  63   }
  64
  65   virtual ~nsStreamStrategy()
  66   {
  67     PR_DestroyLock(mLock);
  68     MOZ_COUNT_DTOR(nsStreamStrategy);
  69   }
  70
  71   // These methods have the same thread calling requirements
  72   // as those with the same name in nsMediaStream
  73
  74   /**
  75    * @param aStreamListener if null, the strategy should open mChannel
  76    * itself. Otherwise, mChannel is already open and the strategy
  77    * should just return its stream listener in aStreamListener (or set
  78    * *aStreamListener to null, if it doesn't need a listener).
  79    */
  80   virtual nsresult Open(nsIStreamListener** aStreamListener) = 0;
  81   virtual nsresult Close() = 0;
  82   virtual nsresult Read(char* aBuffer, PRUint32 aCount, PRUint32* aBytes) = 0;
  83   virtual nsresult Seek(PRInt32 aWhence, PRInt64 aOffset) = 0;
  84   virtual PRInt64  Tell() = 0;
  85   virtual PRUint32 Available() = 0;
  86   virtual float    DownloadRate() = 0;
  87   virtual void     Cancel() { }
  88   virtual nsIPrincipal* GetCurrentPrincipal() = 0;
  89
  90 protected:
  91   // This is not an nsCOMPointer to prevent a circular reference
  92   // between the decoder to the media stream object. The stream never
  93   // outlives the lifetime of the decoder.
  94   nsMediaDecoder* mDecoder;
  95
  96   // Channel used to download the media data. Must be accessed
  97   // from the main thread only.
  98   nsCOMPtr<nsIChannel> mChannel;
  99
 100   // URI in case the stream needs to be re-opened. Access from
 101   // main thread only.
 102   nsCOMPtr<nsIURI> mURI;
 103
 104   // This lock handles synchronisation between calls to Close() and
 105   // the Read, Seek, etc calls. Close must not be called while a
 106   // Read or Seek is in progress since it resets various internal
 107   // values to null.
 108   PRLock* mLock;
 109 };
 110
 111 /*
 112    Provides the ability to open, read and seek into a media stream
 113    (audio, video). Handles the underlying machinery to do range
 114    requests, etc as needed by the actual stream type. Instances of
 115    this class must be created on the main thread.
 116
 117    Open, Close and Cancel must be called on the main thread only. Once
 118    the stream is open the remaining methods (except for Close and
 119    Cancel) may be called on another thread which may be a non main
 120    thread. They may not be called on multiple other threads though. In
 121    the case of the Ogg Decoder they are called on the Decode thread
 122    for example. You must ensure that no threads are calling these
 123    methods once Close is called.
 124 */
 125 class nsMediaStream
 126 {
 127  public:
 128   nsMediaStream();
 129   ~nsMediaStream();
 130
 131   /**
 132    * Create a channel for the stream, reading data from the
 133    * media resource at the URI. Call on main thread only.
 134    * @param aChannel if non-null, this channel is used and aListener
 135    * is set to the listener we want for the channel. aURI must
 136    * be the URI for the channel, obtained via NS_GetFinalChannelURI.
 137    */
 138   nsresult Open(nsMediaDecoder* aDecoder, nsIURI* aURI,
 139                 nsIChannel* aChannel, nsIStreamListener** aListener);
 140
 141   // Close the stream, stop any listeners, channels, etc.
 142   // Call on main thread only.
 143   nsresult Close();
 144
 145   // Read up to aCount bytes from the stream. The buffer must have
 146   // enough room for at least aCount bytes. Stores the number of
 147   // actual bytes read in aBytes (0 on end of file). Can be called
 148   // from any thread. May read less than aCount bytes if the number of
 149   // available bytes is less than aCount. Always check *aBytes after
 150   // read, and call again if necessary.
 151   nsresult Read(char* aBuffer, PRUint32 aCount, PRUint32* aBytes);
 152
 153   // Seek to the given bytes offset in the stream. aWhence can be
 154   // one of:
 155   //   NS_SEEK_SET
 156   //   NS_SEEK_CUR
 157   //   NS_SEEK_END
 158   //
 159   // Can be called from any thread.
 160   nsresult Seek(PRInt32 aWhence, PRInt64 aOffset);
 161
 162   // Report the current offset in bytes from the start of the stream.
 163   // Can be called from any thread.
 164   PRInt64 Tell();
 165
 166   // Return the number of bytes available in the stream that can be
 167   // read without blocking. Can be called from any thread.
 168   PRUint32 Available();
 169
 170   // Return the current download rate in bytes per second. Returns less than
 171   // zero if the download has completed. Can be called from any
 172   // thread.
 173   float DownloadRate();
 174
 175   // Return the current playback rate in bytes per second. Can be
 176   // called from any thread.
 177   float PlaybackRate();
 178
 179   // Cancels any currently blocking request and forces that request to
 180   // return an error. Call on main thread only.
 181   void Cancel();
 182
 183   // Call on main thread only.
 184   nsIPrincipal* GetCurrentPrincipal();
 185
 186  private:
 187   // Strategy object that is used for the handling seeking, etc
 188   // Accessed from any thread. Set on the Open call on the main thread
 189   // only. Open is always called first on the main thread before any
 190   // other calls from other threads.
 191   nsAutoPtr<nsStreamStrategy> mStreamStrategy;
 192
 193   // Time used for computing average playback rate. Written on the
 194   // main thread only during the Open call. Read from any thread during
 195   // calls to PlaybackRate() - which can only ever happen after Open.
 196   PRIntervalTime mPlaybackRateStart;
 197
 198   // Bytes downloaded for average playback rate computation. Initialized
 199   // on the main thread during Open(). After that it is read and written
 200   // possibly on a different thread, but exclusively from that
 201   // thread. In the case of the Ogg Decoder, it is the Decoder thread.
 202   PRUint32 mPlaybackRateCount;
 203 };
 204
 205 #endif