OLD | NEW |
---|---|
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef MEDIA_BASE_DECRYPTOR_H_ | 5 #ifndef MEDIA_BASE_DECRYPTOR_H_ |
6 #define MEDIA_BASE_DECRYPTOR_H_ | 6 #define MEDIA_BASE_DECRYPTOR_H_ |
7 | 7 |
8 #include <string> | 8 #include <string> |
9 | 9 |
10 #include "base/basictypes.h" | 10 #include "base/basictypes.h" |
11 #include "base/callback.h" | 11 #include "base/callback.h" |
12 #include "base/memory/ref_counted.h" | 12 #include "base/memory/ref_counted.h" |
13 #include "media/base/media_export.h" | 13 #include "media/base/media_export.h" |
14 | 14 |
15 namespace media { | 15 namespace media { |
16 | 16 |
17 class DecoderBuffer; | 17 class DecoderBuffer; |
18 class VideoDecoderConfig; | |
19 class VideoFrame; | |
18 | 20 |
19 // Performs key operations and decrypts encrypted buffer. | 21 // Performs key operations and decrypts (and decodes) encrypted buffer. |
20 // All public methods other than Decrypt() will be called on the renderer | 22 // |
21 // thread. Therefore, these calls should be fast and nonblocking, with key | 23 // Key operations (GenerateKeyRequest(), AddKey() and CancelKeyRequest()) |
22 // events fired asynchronously. Decrypt() will be called on the (video/audio) | 24 // are called on the renderer thread. Therefore, these calls should be fast |
23 // decoder thread. | 25 // and nonblocking; key events should be fired asynchronously. |
26 // All other methods are called on the (video/audio) decoder thread. | |
27 // Decryptor implementations must be thread safe when methods are called | |
28 // following the above model. | |
29 // | |
30 // Note that all callbacks can be fired synchronously or asynchronously. | |
scherkus (not reviewing)
2012/10/04 00:15:13
hmm.. how about "Depending on the implementation c
xhwang
2012/10/04 16:32:54
Done.
| |
24 class MEDIA_EXPORT Decryptor { | 31 class MEDIA_EXPORT Decryptor { |
25 public: | 32 public: |
26 enum KeyError { | 33 enum KeyError { |
27 kUnknownError = 1, | 34 kUnknownError = 1, |
28 kClientError, | 35 kClientError, |
29 kServiceError, | 36 kServiceError, |
30 kOutputError, | 37 kOutputError, |
31 kHardwareChangeError, | 38 kHardwareChangeError, |
32 kDomainError | 39 kDomainError |
33 }; | 40 }; |
34 | 41 |
35 enum Status { | 42 enum Status { |
36 kSuccess, // Decryption successfully completed. Decrypted buffer ready. | 43 kSuccess, // Decryption successfully completed. Decrypted buffer ready. |
37 kNoKey, // No key is available to decrypt. | 44 kNoKey, // No key is available to decrypt. |
45 kNeedMoreData, // Decoder needs more data to produce a frame. | |
38 kError // Key is available but an error occurred during decryption. | 46 kError // Key is available but an error occurred during decryption. |
39 }; | 47 }; |
40 | 48 |
41 Decryptor() {} | 49 Decryptor(); |
42 virtual ~Decryptor() {} | 50 virtual ~Decryptor(); |
43 | 51 |
44 // Generates a key request for the |key_system| with |init_data| provided. | 52 // Generates a key request for the |key_system| with |init_data| provided. |
45 // Returns true if generating key request succeeded, false otherwise. | 53 // Returns true if generating key request succeeded, false otherwise. |
46 // Note: AddKey() and CancelKeyRequest() should only be called after | 54 // Note: AddKey() and CancelKeyRequest() should only be called after |
47 // GenerateKeyRequest() returns true. | 55 // GenerateKeyRequest() returns true. |
48 virtual bool GenerateKeyRequest(const std::string& key_system, | 56 virtual bool GenerateKeyRequest(const std::string& key_system, |
49 const uint8* init_data, | 57 const uint8* init_data, |
50 int init_data_length) = 0; | 58 int init_data_length) = 0; |
51 | 59 |
52 // Adds a |key| to the |key_system|. The |key| is not limited to a decryption | 60 // Adds a |key| to the |key_system|. The |key| is not limited to a decryption |
53 // key. It can be any data that the key system accepts, such as a license. | 61 // key. It can be any data that the key system accepts, such as a license. |
54 // If multiple calls of this function set different keys for the same | 62 // If multiple calls of this function set different keys for the same |
55 // key ID, the older key will be replaced by the newer key. | 63 // key ID, the older key will be replaced by the newer key. |
56 virtual void AddKey(const std::string& key_system, | 64 virtual void AddKey(const std::string& key_system, |
57 const uint8* key, | 65 const uint8* key, |
58 int key_length, | 66 int key_length, |
59 const uint8* init_data, | 67 const uint8* init_data, |
60 int init_data_length, | 68 int init_data_length, |
61 const std::string& session_id) = 0; | 69 const std::string& session_id) = 0; |
62 | 70 |
63 // Cancels the key request specified by |session_id|. | 71 // Cancels the key request specified by |session_id|. |
64 virtual void CancelKeyRequest(const std::string& key_system, | 72 virtual void CancelKeyRequest(const std::string& key_system, |
65 const std::string& session_id) = 0; | 73 const std::string& session_id) = 0; |
66 | 74 |
75 // Indicates completion of a decryption operation. | |
76 // | |
77 // First parameter: The status of the decryption operation. | |
78 // - Set to kSuccess if the encrypted buffer is successfully decrypted and | |
79 // the decrypted buffer is ready to be read. | |
80 // - Set to kNoKey if no decryption key is available to decrypt the encrypted | |
81 // buffer. In this case the decrypted buffer must be NULL. | |
82 // - Set to kError if unexpected error has occurred. In this case the | |
83 // decrypted buffer must be NULL. | |
84 // - This parameter should not be set to kNeedMoreData. | |
85 // Second parameter: The decrypted buffer. | |
86 typedef base::Callback<void(Status, | |
87 const scoped_refptr<DecoderBuffer>&)> DecryptCB; | |
88 | |
67 // Decrypts the |encrypted| buffer. The decrypt status and decrypted buffer | 89 // Decrypts the |encrypted| buffer. The decrypt status and decrypted buffer |
68 // are returned via the provided callback |decrypt_cb|. The |encrypted| buffer | 90 // are returned via the provided callback |decrypt_cb|. The |encrypted| buffer |
69 // must not be NULL. | 91 // must not be NULL. |
70 // | |
71 // Note that the callback maybe called synchronously or asynchronously. | |
72 // | |
73 // If the returned status is kSuccess, the |encrypted| buffer is successfully | |
74 // decrypted and the decrypted buffer is ready to be read. | |
75 // If the returned status is kNoKey, no decryption key is available to decrypt | |
76 // |encrypted| buffer. In this case the decrypted buffer must be NULL. | |
77 // If the returned status is kError, unexpected error has occurred. In this | |
78 // case the decrypted buffer must be NULL. | |
79 typedef base::Callback<void(Status, | |
80 const scoped_refptr<DecoderBuffer>&)> DecryptCB; | |
81 virtual void Decrypt(const scoped_refptr<DecoderBuffer>& encrypted, | 92 virtual void Decrypt(const scoped_refptr<DecoderBuffer>& encrypted, |
82 const DecryptCB& decrypt_cb) = 0; | 93 const DecryptCB& decrypt_cb) = 0; |
83 | 94 |
84 // Cancel scheduled decryption operations and fires any pending DecryptCB | 95 // Cancel scheduled decryption operations and fires any pending DecryptCB |
85 // immediately with kError and NULL buffer. | 96 // immediately with kError and NULL buffer. |
86 virtual void CancelDecrypt() = 0; | 97 virtual void CancelDecrypt() = 0; |
87 | 98 |
99 // Indicates completion of decoder initialization. | |
100 // | |
101 // First Parameter: Indicates initialization success. | |
102 // - Set to true if initialization was successful. False if an error occurred. | |
103 typedef base::Callback<void(bool)> DecoderInitCB; | |
104 | |
105 // Initializes a video decoder with the given |config|, executing the | |
106 // |init_cb| upon completion. | |
107 // Note: DecryptAndDecodeVideo(), ResetVideoDecoder() and StopVideoDecoder() | |
108 // can only be called after InitializeVideoDecoder() succeeded. | |
109 virtual void InitializeVideoDecoder(const VideoDecoderConfig& config, | |
110 const DecoderInitCB& init_cb) = 0; | |
111 | |
112 // Indicates completion of video decrypting and decoding operation. | |
113 // | |
114 // First parameter: The status of the decrypting and decoding operation. | |
115 // - Set to kSuccess if the encrypted buffer is successfully decrypted and | |
116 // decoded. In this case, the decoded video frame can be: | |
117 // 1) NULL, which means the operation has been aborted. | |
118 // 2) End-of-stream (EOS) frame, which means that the decoder has hit EOS, | |
119 // flushed all internal buffers and cannot produce more video frames. | |
120 // 3) Decrypted and decoded video frame. | |
121 // - Set to kNoKey if no decryption key is available to decrypt the encrypted | |
122 // buffer. In this case the decoded video frame must be NULL. | |
123 // - Set to kNeedMoreData if more data is needed to produce a video frame. In | |
124 // this case the decoded video frame must be NULL. | |
125 // - Set to kError if unexpected error has occurred. In this case the | |
126 // decoded video frame must be NULL. | |
127 // Second parameter: The decoded video frame. | |
128 typedef base::Callback<void(Status, | |
129 const scoped_refptr<VideoFrame>&)> VideoDecodeCB; | |
130 | |
131 // Decrypts and decodes the |encrypted| buffer. The status and the decrypted | |
132 // buffer are returned via the provided callback |video_decode_cb|. | |
133 // The |encrypted| buffer must not be NULL. | |
134 // At end-of-stream, this method should be called repeatedly with | |
135 // end-of-stream DecoderBuffer until no video frame can be produced. | |
136 virtual void DecryptAndDecodeVideo( | |
137 const scoped_refptr<DecoderBuffer>& encrypted, | |
138 const VideoDecodeCB& video_decode_cb) = 0; | |
139 | |
140 // Cancels scheduled video decrypt-and-decode operations and fires any pending | |
141 // VideoDecodeCB immediately with kError and NULL frame. | |
142 virtual void CancelDecryptAndDecodeVideo() = 0; | |
143 | |
144 // Stops decoder and sets it to an uninitialized state. | |
145 // The decoder can be reinitialized by calling InitializeVideoDecoder() after | |
146 // it is stopped. | |
147 virtual void StopVideoDecoder() = 0; | |
148 | |
88 private: | 149 private: |
89 DISALLOW_COPY_AND_ASSIGN(Decryptor); | 150 DISALLOW_COPY_AND_ASSIGN(Decryptor); |
90 }; | 151 }; |
91 | 152 |
92 } // namespace media | 153 } // namespace media |
93 | 154 |
94 #endif // MEDIA_BASE_DECRYPTOR_H_ | 155 #endif // MEDIA_BASE_DECRYPTOR_H_ |
OLD | NEW |