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 a decryptor is ready. 165 typedef base::Callback<void(Decryptor*)> DecryptorReadyCB; 166 167 // Callback to set/cancel a DecryptorReadyCB. 168 // Calling this callback with a non-null callback registers decryptor ready 169 // notification. When the decryptor is ready, notification will be sent 170 // through the provided callback. 171 // Calling this callback with a null callback cancels previously registered 172 // decryptor ready notification. Any previously provided callback will be 173 // fired immediately with NULL. 174 typedef base::Callback<void(const DecryptorReadyCB&)> SetDecryptorReadyCB; 175 176 } // namespace media 177 178 #endif // MEDIA_BASE_DECRYPTOR_H_ 179