src/media/base/decryptor.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_DECRYPTOR_H_
   6 #define MEDIA_BASE_DECRYPTOR_H_
   7
   8 #include <list>
   9
  10 #include "base/basictypes.h"
  11 #include "base/callback.h"
  12 #include "base/memory/ref_counted.h"
  13 #include "media/base/audio_buffer.h"
  14 #include "media/base/media_export.h"
  15
  16 namespace media {
  17
  18 class AudioDecoderConfig;
  19 class DecoderBuffer;
  20 class VideoDecoderConfig;
  21 class VideoFrame;
  22
  23 // Decrypts (and decodes) encrypted buffer.
  24 //
  25 // All methods are called on the (video/audio) decoder thread. Decryptor
  26 // implementations must be thread safe when methods are called this way.
  27 // Depending on the implementation callbacks may be fired synchronously or
  28 // asynchronously.
  29 class MEDIA_EXPORT Decryptor {
  30  public:
  31   // TODO(xhwang): Replace kError with kDecryptError and kDecodeError.
  32   // TODO(xhwang): Replace kNeedMoreData with kNotEnoughData.
  33   enum Status {
  34     kSuccess,  // Decryption successfully completed. Decrypted buffer ready.
  35     kNoKey,  // No key is available to decrypt.
  36     kNeedMoreData,  // Decoder needs more data to produce a frame.
  37     kError  // Key is available but an error occurred during decryption.
  38   };
  39
  40   // TODO(xhwang): Unify this with DemuxerStream::Type.
  41   enum StreamType {
  42     kAudio,
  43     kVideo
  44   };
  45
  46   Decryptor();
  47   virtual ~Decryptor();
  48
  49   // Indicates that a new key has been added to the MediaKeys object associated
  50   // with the Decryptor.
  51   typedef base::Callback<void()> NewKeyCB;
  52
  53   // Registers a NewKeyCB which should be called when a new key is added to the
  54   // decryptor. Only one NewKeyCB can be registered for one |stream_type|.
  55   // If this function is called multiple times for the same |stream_type|, the
  56   // previously registered callback will be replaced. In other words,
  57   // registering a null callback cancels the originally registered callback.
  58   virtual void RegisterNewKeyCB(StreamType stream_type,
  59                                 const NewKeyCB& key_added_cb) = 0;
  60
  61   // Indicates completion of a decryption operation.
  62   //
  63   // First parameter: The status of the decryption operation.
  64   // - Set to kSuccess if the encrypted buffer is successfully decrypted and
  65   //   the decrypted buffer is ready to be read.
  66   // - Set to kNoKey if no decryption key is available to decrypt the encrypted
  67   //   buffer. In this case the decrypted buffer must be NULL.
  68   // - Set to kError if unexpected error has occurred. In this case the
  69   //   decrypted buffer must be NULL.
  70   // - This parameter should not be set to kNeedMoreData.
  71   // Second parameter: The decrypted buffer.
  72   typedef base::Callback<void(Status,
  73                               const scoped_refptr<DecoderBuffer>&)> DecryptCB;
  74
  75   // Decrypts the |encrypted| buffer. The decrypt status and decrypted buffer
  76   // are returned via the provided callback |decrypt_cb|. The |encrypted| buffer
  77   // must not be NULL.
  78   // Decrypt() should not be called until any previous DecryptCB of the same
  79   // |stream_type| has completed. Thus, only one DecryptCB may be pending at
  80   // a time for a given |stream_type|.
  81   virtual void Decrypt(StreamType stream_type,
  82                        const scoped_refptr<DecoderBuffer>& encrypted,
  83                        const DecryptCB& decrypt_cb) = 0;
  84
  85   // Cancels the scheduled decryption operation for |stream_type| and fires the
  86   // pending DecryptCB immediately with kSuccess and NULL.
  87   // Decrypt() should not be called again before the pending DecryptCB for the
  88   // same |stream_type| is fired.
  89   virtual void CancelDecrypt(StreamType stream_type) = 0;
  90
  91   // Indicates completion of audio/video decoder initialization.
  92   //
  93   // First Parameter: Indicates initialization success.
  94   // - Set to true if initialization was successful. False if an error occurred.
  95   typedef base::Callback<void(bool)> DecoderInitCB;
  96
  97   // Initializes a decoder with the given |config|, executing the |init_cb|
  98   // upon completion.
  99   virtual void InitializeAudioDecoder(const AudioDecoderConfig& config,
 100                                       const DecoderInitCB& init_cb) = 0;
 101   virtual void InitializeVideoDecoder(const VideoDecoderConfig& config,
 102                                       const DecoderInitCB& init_cb) = 0;
 103
 104   // Helper structure for managing multiple decoded audio buffers per input.
 105   // TODO(xhwang): Rename this to AudioFrames.
 106   typedef std::list<scoped_refptr<AudioBuffer> > AudioBuffers;
 107
 108   // Indicates completion of audio/video decrypt-and-decode operation.
 109   //
 110   // First parameter: The status of the decrypt-and-decode operation.
 111   // - Set to kSuccess if the encrypted buffer is successfully decrypted and
 112   //   decoded. In this case, the decoded frame/buffers can be/contain:
 113   //   1) NULL, which means the operation has been aborted.
 114   //   2) End-of-stream (EOS) frame, which means that the decoder has hit EOS,
 115   //      flushed all internal buffers and cannot produce more video frames.
 116   //   3) Decrypted and decoded video frame or audio buffer.
 117   // - Set to kNoKey if no decryption key is available to decrypt the encrypted
 118   //   buffer. In this case the returned frame(s) must be NULL/empty.
 119   // - Set to kNeedMoreData if more data is needed to produce a video frame. In
 120   //   this case the returned frame(s) must be NULL/empty.
 121   // - Set to kError if unexpected error has occurred. In this case the
 122   //   returned frame(s) must be NULL/empty.
 123   // Second parameter: The decoded video frame or audio buffers.
 124   typedef base::Callback<void(Status, const AudioBuffers&)> AudioDecodeCB;
 125   typedef base::Callback<void(Status,
 126                               const scoped_refptr<VideoFrame>&)> VideoDecodeCB;
 127
 128   // Decrypts and decodes the |encrypted| buffer. The status and the decrypted
 129   // buffer are returned via the provided callback.
 130   // The |encrypted| buffer must not be NULL.
 131   // At end-of-stream, this method should be called repeatedly with
 132   // end-of-stream DecoderBuffer until no frame/buffer can be produced.
 133   // These methods can only be called after the corresponding decoder has
 134   // been successfully initialized.
 135   virtual void DecryptAndDecodeAudio(
 136       const scoped_refptr<DecoderBuffer>& encrypted,
 137       const AudioDecodeCB& audio_decode_cb) = 0;
 138   virtual void DecryptAndDecodeVideo(
 139       const scoped_refptr<DecoderBuffer>& encrypted,
 140       const VideoDecodeCB& video_decode_cb) = 0;
 141
 142   // Resets the decoder to an initialized clean state, cancels any scheduled
 143   // decrypt-and-decode operations, and fires any pending
 144   // AudioDecodeCB/VideoDecodeCB immediately with kError and NULL.
 145   // This method can only be called after the corresponding decoder has been
 146   // successfully initialized.
 147   virtual void ResetDecoder(StreamType stream_type) = 0;
 148
 149   // Releases decoder resources, deinitializes the decoder, cancels any
 150   // scheduled initialization or decrypt-and-decode operations, and fires
 151   // any pending DecoderInitCB/AudioDecodeCB/VideoDecodeCB immediately.
 152   // DecoderInitCB should be fired with false. AudioDecodeCB/VideoDecodeCB
 153   // should be fired with kError.
 154   // This method can be called any time after Initialize{Audio|Video}Decoder()
 155   // has been called (with the correct stream type).
 156   // After this operation, the decoder is set to an uninitialized state.
 157   // The decoder can be reinitialized after it is uninitialized.
 158   virtual void DeinitializeDecoder(StreamType stream_type) = 0;
 159
 160  private:
 161   DISALLOW_COPY_AND_ASSIGN(Decryptor);
 162 };
 163
 164 // Callback to notify that the decryptor has been completely attached into the
 165 // pipeline. Parameter indicates whether the operation succeeded.
 166 typedef base::Callback<void(bool)> DecryptorAttachedCB;
 167
 168 // Callback to notify that a decryptor is ready. DecryptorAttachedCB is called
 169 // when the decryptor has been completely inserted into the pipeline.
 170 typedef base::Callback<void(Decryptor*, const DecryptorAttachedCB&)>
 171     DecryptorReadyCB;
 172
 173 // Callback to set/cancel a DecryptorReadyCB.
 174 // Calling this callback with a non-null callback registers decryptor ready
 175 // notification. When the decryptor is ready, notification will be sent
 176 // through the provided callback.
 177 // Calling this callback with a null callback cancels previously registered
 178 // decryptor ready notification. Any previously provided callback will be
 179 // fired immediately with NULL.
 180 typedef base::Callback<void(const DecryptorReadyCB&)> SetDecryptorReadyCB;
 181
 182 }  // namespace media
 183
 184 #endif  // MEDIA_BASE_DECRYPTOR_H_