decryptor.h revision 6e8cce623b6e4fe0c9e4af605d675dd9d0338c38
17dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// Copyright (c) 2012 The Chromium Authors. All rights reserved. 27dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// Use of this source code is governed by a BSD-style license that can be 37dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// found in the LICENSE file. 47dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 57dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#ifndef MEDIA_BASE_DECRYPTOR_H_ 67dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#define MEDIA_BASE_DECRYPTOR_H_ 77dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 87dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#include <list> 97dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 107dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#include "base/basictypes.h" 11f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles)#include "base/callback.h" 127dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#include "base/memory/ref_counted.h" 137dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#include "media/base/audio_buffer.h" 147dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch#include "media/base/media_export.h" 157dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 167dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochnamespace media { 177dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 187dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochclass AudioDecoderConfig; 197dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochclass DecoderBuffer; 207dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochclass VideoDecoderConfig; 217dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochclass VideoFrame; 227dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 237dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// Decrypts (and decodes) encrypted buffer. 247dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// 257dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// All methods are called on the (video/audio) decoder thread. Decryptor 267dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// implementations must be thread safe when methods are called this way. 277dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// Depending on the implementation callbacks may be fired synchronously or 287dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch// asynchronously. 297dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdochclass MEDIA_EXPORT Decryptor { 307dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch public: 317dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // TODO(xhwang): Replace kError with kDecryptError and kDecodeError. 327dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // TODO(xhwang): Replace kNeedMoreData with kNotEnoughData. 337dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch enum Status { 347dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kSuccess, // Decryption successfully completed. Decrypted buffer ready. 357dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kNoKey, // No key is available to decrypt. 367dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kNeedMoreData, // Decoder needs more data to produce a frame. 377dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kError // Key is available but an error occurred during decryption. 387dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch }; 397dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 407dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // TODO(xhwang): Unify this with DemuxerStream::Type. 417dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch enum StreamType { 427dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kAudio, 437dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch kVideo 447dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch }; 457dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 467dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch Decryptor(); 477dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual ~Decryptor(); 487dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 497dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Indicates that a new key has been added to the MediaKeys object associated 507dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // with the Decryptor. 517dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef base::Callback<void()> NewKeyCB; 527dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 537dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Registers a NewKeyCB which should be called when a new key is added to the 547dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // decryptor. Only one NewKeyCB can be registered for one |stream_type|. 557dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // If this function is called multiple times for the same |stream_type|, the 567dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // previously registered callback will be replaced. In other words, 577dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // registering a null callback cancels the originally registered callback. 587dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void RegisterNewKeyCB(StreamType stream_type, 597dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const NewKeyCB& key_added_cb) = 0; 607dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 617dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Indicates completion of a decryption operation. 627dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // 637dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // First parameter: The status of the decryption operation. 647dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kSuccess if the encrypted buffer is successfully decrypted and 657dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // the decrypted buffer is ready to be read. 667dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kNoKey if no decryption key is available to decrypt the encrypted 677dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // buffer. In this case the decrypted buffer must be NULL. 687dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kError if unexpected error has occurred. In this case the 697dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // decrypted buffer must be NULL. 707dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - This parameter should not be set to kNeedMoreData. 717dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Second parameter: The decrypted buffer. 727dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef base::Callback<void(Status, 737dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const scoped_refptr<DecoderBuffer>&)> DecryptCB; 747dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 757dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Decrypts the |encrypted| buffer. The decrypt status and decrypted buffer 767dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // are returned via the provided callback |decrypt_cb|. The |encrypted| buffer 777dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // must not be NULL. 787dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Decrypt() should not be called until any previous DecryptCB of the same 797dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // |stream_type| has completed. Thus, only one DecryptCB may be pending at 807dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // a time for a given |stream_type|. 817dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void Decrypt(StreamType stream_type, 82f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles) const scoped_refptr<DecoderBuffer>& encrypted, 837dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const DecryptCB& decrypt_cb) = 0; 847dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 857dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Cancels the scheduled decryption operation for |stream_type| and fires the 867dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // pending DecryptCB immediately with kSuccess and NULL. 877dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Decrypt() should not be called again before the pending DecryptCB for the 887dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // same |stream_type| is fired. 897dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void CancelDecrypt(StreamType stream_type) = 0; 907dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 917dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Indicates completion of audio/video decoder initialization. 92f2477e01787aa58f445919b809d89e252beef54fTorne (Richard Coles) // 937dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // First Parameter: Indicates initialization success. 947dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to true if initialization was successful. False if an error occurred. 957dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef base::Callback<void(bool)> DecoderInitCB; 967dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 977dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Initializes a decoder with the given |config|, executing the |init_cb| 987dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // upon completion. 997dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void InitializeAudioDecoder(const AudioDecoderConfig& config, 1007dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const DecoderInitCB& init_cb) = 0; 1017dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void InitializeVideoDecoder(const VideoDecoderConfig& config, 1027dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const DecoderInitCB& init_cb) = 0; 1037dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1047dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Helper structure for managing multiple decoded audio buffers per input. 1057dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // TODO(xhwang): Rename this to AudioFrames. 1067dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef std::list<scoped_refptr<AudioBuffer> > AudioBuffers; 1077dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1087dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Indicates completion of audio/video decrypt-and-decode operation. 1097dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // 1107dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // First parameter: The status of the decrypt-and-decode operation. 1117dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kSuccess if the encrypted buffer is successfully decrypted and 1127dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // decoded. In this case, the decoded frame/buffers can be/contain: 1137dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // 1) NULL, which means the operation has been aborted. 1147dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // 2) End-of-stream (EOS) frame, which means that the decoder has hit EOS, 1157dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // flushed all internal buffers and cannot produce more video frames. 1167dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // 3) Decrypted and decoded video frame or audio buffer. 1177dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kNoKey if no decryption key is available to decrypt the encrypted 1187dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // buffer. In this case the returned frame(s) must be NULL/empty. 1197dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kNeedMoreData if more data is needed to produce a video frame. In 1207dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // this case the returned frame(s) must be NULL/empty. 1217dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // - Set to kError if unexpected error has occurred. In this case the 1227dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // returned frame(s) must be NULL/empty. 1237dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Second parameter: The decoded video frame or audio buffers. 1247dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef base::Callback<void(Status, const AudioBuffers&)> AudioDecodeCB; 1257dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch typedef base::Callback<void(Status, 1267dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const scoped_refptr<VideoFrame>&)> VideoDecodeCB; 1277dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1287dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Decrypts and decodes the |encrypted| buffer. The status and the decrypted 1297dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // buffer are returned via the provided callback. 1307dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // The |encrypted| buffer must not be NULL. 1317dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // At end-of-stream, this method should be called repeatedly with 1327dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // end-of-stream DecoderBuffer until no frame/buffer can be produced. 1337dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // These methods can only be called after the corresponding decoder has 1347dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // been successfully initialized. 1357dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void DecryptAndDecodeAudio( 1367dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const scoped_refptr<DecoderBuffer>& encrypted, 1377dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const AudioDecodeCB& audio_decode_cb) = 0; 1387dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void DecryptAndDecodeVideo( 1397dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const scoped_refptr<DecoderBuffer>& encrypted, 1407dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch const VideoDecodeCB& video_decode_cb) = 0; 1417dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1427dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Resets the decoder to an initialized clean state, cancels any scheduled 1437dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // decrypt-and-decode operations, and fires any pending 1447dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // AudioDecodeCB/VideoDecodeCB immediately with kError and NULL. 1457dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // This method can only be called after the corresponding decoder has been 1467dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // successfully initialized. 1477dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void ResetDecoder(StreamType stream_type) = 0; 1487dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1497dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // Releases decoder resources, deinitializes the decoder, cancels any 1507dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // scheduled initialization or decrypt-and-decode operations, and fires 1517dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // any pending DecoderInitCB/AudioDecodeCB/VideoDecodeCB immediately. 1527dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // DecoderInitCB should be fired with false. AudioDecodeCB/VideoDecodeCB 1537dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // should be fired with kError. 1547dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // This method can be called any time after Initialize{Audio|Video}Decoder() 1557dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // has been called (with the correct stream type). 1567dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // After this operation, the decoder is set to an uninitialized state. 1577dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch // The decoder can be reinitialized after it is uninitialized. 1587dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch virtual void DeinitializeDecoder(StreamType stream_type) = 0; 1597dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 1607dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch private: 1617dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch DISALLOW_COPY_AND_ASSIGN(Decryptor); 1627dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch}; 163 164// Callback to notify that the decryptor has been completely attached into the 165// pipeline. Parameter indicates whether the operation succeeded. 166typedef 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. 170typedef 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. 180typedef base::Callback<void(const DecryptorReadyCB&)> SetDecryptorReadyCB; 181 182} // namespace media 183 184#endif // MEDIA_BASE_DECRYPTOR_H_ 185