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
16namespace media {
17
18class AudioDecoderConfig;
19class DecoderBuffer;
20class VideoDecoderConfig;
21class 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.
29class 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.
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