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
6/**
7 * This file defines the <code>PPP_ContentDecryptor_Private</code>
8 * interface. Note: This is a special interface, only to be used for Content
9 * Decryption Modules, not normal plugins.
10 */
11label Chrome {
12  M36 = 0.12
13};
14
15/**
16 * <code>PPP_ContentDecryptor_Private</code> structure contains the function
17 * pointers the decryption plugin must implement to provide services needed by
18 * the browser. This interface provides the plugin side support for the Content
19 * Decryption Module (CDM) for Encrypted Media Extensions:
20 * http://www.w3.org/TR/encrypted-media/
21 */
22interface PPP_ContentDecryptor_Private {
23  /**
24   * Initialize for the specified key system.
25   *
26   * @param[in] key_system A <code>PP_Var</code> of type
27   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
28   */
29  void Initialize(
30      [in] PP_Instance instance,
31      [in] PP_Var key_system);
32
33  /**
34   * Provides a server certificate to be used to encrypt messages to the
35   * license server.
36   *
37   * @param[in] promise_id A reference for the promise that gets resolved or
38   * rejected depending upon the success or failure of setting the certificate.
39   *
40   * @param[in] server_certificate A <code>PP_Var</code> of type
41   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the certificate to be used.
42   */
43  void SetServerCertificate(
44      [in] PP_Instance instance,
45      [in] uint32_t promise_id,
46      [in] PP_Var server_certificate);
47
48  /**
49   * Creates a session. <code>init_data_type</code> contains the MIME type of
50   * <code>init_data</code>. <code>init_data</code> is a data buffer
51   * containing data for use in generating the request.
52   *
53   * Note: <code>CreateSession()</code> must create a web session ID and provide
54   * it to the browser via <code>SessionCreated()</code> on the
55   * <code>PPB_ContentDecryptor_Private</code> interface.
56   *
57   * @param[in] promise_id A reference for the promise that gets resolved or
58   * rejected depending upon the success or failure when creating the session.
59   *
60   * @param[in] init_data_type A <code>PP_Var</code> of type
61   * <code>PP_VARTYPE_STRING</code> containing the MIME type for init_data.
62   *
63   * @param[in] init_data A <code>PP_Var</code> of type
64   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific
65   * initialization data.
66   *
67   * @param[in] session_type A <code>PP_SessionType</code> that indicates the
68   * type of session to be created.
69   */
70  void CreateSession(
71      [in] PP_Instance instance,
72      [in] uint32_t promise_id,
73      [in] PP_Var init_data_type,
74      [in] PP_Var init_data,
75      [in] PP_SessionType session_type);
76
77  /**
78   * Loads a session whose web session ID is <code>web_session_id</code>.
79   *
80   * Note: After the session is successfully loaded, the CDM must call
81   * <code>SessionCreated()</code> with <code>web_session_id</code> on the
82   * <code>PPB_ContentDecryptor_Private</code> interface.
83   *
84   * @param[in] promise_id A reference for the promise that gets resolved or
85   * rejected depending upon the success or failure of loading the session.
86   *
87   * @param[in] web_session_id A <code>PP_Var</code> of type
88   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
89   * to load.
90   */
91  void LoadSession(
92      [in] PP_Instance instance,
93      [in] uint32_t promise_id,
94      [in] PP_Var web_session_id);
95
96  /**
97   * Provides a license or other message to the decryptor.
98   *
99   * When the CDM needs more information, it must call
100   * <code>SessionMessage()</code> on the
101   * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
102   * must notify the web application. When the CDM has finished processing
103   * <code>response</code> and needs no more information, it must call
104   * <code>SessionReady()</code> on the
105   * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
106   * must notify the web application.
107   *
108   * @param[in] promise_id A reference for the promise that gets resolved or
109   * rejected depending upon the success or failure of updating the session.
110   *
111   * @param[in] web_session_id A <code>PP_Var</code> of type
112   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
113   * to be updated.
114   *
115   * @param[in] response A <code>PP_Var</code> of type
116   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the license or other
117   * message for the given session ID.
118   */
119  void UpdateSession(
120      [in] PP_Instance instance,
121      [in] uint32_t promise_id,
122      [in] PP_Var web_session_id,
123      [in] PP_Var response);
124
125  /**
126   * Close the specified session and related resources.
127   *
128   * @param[in] promise_id A reference for the promise that gets resolved or
129   * rejected depending upon the success or failure of closing the session.
130   *
131   * @param[in] web_session_id A <code>PP_Var</code> of type
132   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
133   * to be closed.
134   *
135   */
136  void CloseSession(
137      [in] PP_Instance instance,
138      [in] uint32_t promise_id,
139      [in] PP_Var web_session_id);
140
141  /**
142   * Remove stored data associated with this session.
143   *
144   * @param[in] promise_id A reference for the promise that gets resolved or
145   * rejected depending upon the success or failure of removing the session
146   * data.
147   *
148   * @param[in] web_session_id A <code>PP_Var</code> of type
149   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
150   * to be removed.
151   *
152   */
153  void RemoveSession(
154      [in] PP_Instance instance,
155      [in] uint32_t promise_id,
156      [in] PP_Var web_session_id);
157
158  /**
159   * Get the key IDs for keys in the session that the CDM knows are currently
160   * usable to decrypt media data.
161   *
162   * @param[in] promise_id A reference for the promise that gets resolved or
163   * rejected depending upon the success or failure of obtaining the key IDs.
164   *
165   * @param[in] web_session_id A <code>PP_Var</code> of type
166   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
167   * to be queried.
168   *
169   */
170  void GetUsableKeyIds(
171      [in] PP_Instance instance,
172      [in] uint32_t promise_id,
173      [in] PP_Var web_session_id);
174
175  /**
176   * Decrypts the block and returns the unencrypted block via
177   * <code>DeliverBlock()</code> on the
178   * <code>PPB_ContentDecryptor_Private</code> interface. The returned block
179   * contains encoded data.
180   *
181   * @param[in] resource A <code>PP_Resource</code> corresponding to a
182   * <code>PPB_Buffer_Dev</code> resource that contains an encrypted data
183   * block.
184   *
185   * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
186   * contains all auxiliary information needed for decryption of the
187   * <code>encrypted_block</code>.
188   */
189  void Decrypt(
190      [in] PP_Instance instance,
191      [in] PP_Resource encrypted_block,
192      [in] PP_EncryptedBlockInfo encrypted_block_info);
193
194 /**
195  * Initializes the audio decoder using codec and settings in
196  * <code>decoder_config</code>, and returns the result of the initialization
197  * request to the browser using the <code>DecoderInitializeDone()</code> method
198  * on the <code>PPB_ContentDecryptor_Private</code> interface.
199  *
200  * @param[in] decoder_config A <code>PP_AudioDecoderConfig</code> that
201  * contains audio decoder settings and a request ID. The request ID is passed
202  * to the <code>DecoderInitializeDone()</code> method on the
203  * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
204  * associate the result with a audio decoder initialization request.
205  *
206  * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
207  * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
208  * by some codecs. It should be set to 0 when the codec being initialized
209  * does not require it.
210  */
211  void InitializeAudioDecoder(
212      [in] PP_Instance instance,
213      [in] PP_AudioDecoderConfig decoder_config,
214      [in] PP_Resource codec_extra_data);
215
216 /**
217  * Initializes the video decoder using codec and settings in
218  * <code>decoder_config</code>, and returns the result of the initialization
219  * request to the browser using the <code>DecoderInitializeDone()</code>
220  * method on the <code>PPB_ContentDecryptor_Private</code> interface.
221  *
222  * @param[in] decoder_config A <code>PP_VideoDecoderConfig</code> that
223  * contains video decoder settings and a request ID. The request ID is passed
224  * to the <code>DecoderInitializeDone()</code> method on the
225  * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
226  * associate the result with a video decoder initialization request.
227  *
228  * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
229  * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
230  * by some codecs. It should be set to 0 when the codec being initialized
231  * does not require it.
232  */
233  void InitializeVideoDecoder(
234      [in] PP_Instance instance,
235      [in] PP_VideoDecoderConfig decoder_config,
236      [in] PP_Resource codec_extra_data);
237
238  /**
239   * De-initializes the decoder for the <code>PP_DecryptorStreamType</code>
240   * specified by <code>decoder_type</code> and sets it to an uninitialized
241   * state. The decoder can be re-initialized after de-initialization completes
242   * by calling <code>InitializeAudioDecoder</code> or
243   * <code>InitializeVideoDecoder</code>.
244   *
245   * De-initialization completion is reported to the browser using the
246   * <code>DecoderDeinitializeDone()</code> method on the
247   * <code>PPB_ContentDecryptor_Private</code> interface.
248   *
249   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
250   * specifies the decoder to de-initialize.
251   *
252   * @param[in] request_id A request ID that allows the browser to associate a
253   * request to de-initialize a decoder with the corresponding call to the
254   * <code>DecoderDeinitializeDone()</code> method on the
255   * <code>PPB_ContentDecryptor_Private</code> interface.
256   */
257  void DeinitializeDecoder(
258      [in] PP_Instance instance,
259      [in] PP_DecryptorStreamType decoder_type,
260      [in] uint32_t request_id);
261
262  /**
263   * Resets the decoder for the <code>PP_DecryptorStreamType</code> specified
264   * by <code>decoder_type</code> to an initialized clean state. Reset
265   * completion is reported to the browser using the
266   * <code>DecoderResetDone()</code> method on the
267   * <code>PPB_ContentDecryptor_Private</code> interface. This method can be
268   * used to signal a discontinuity in the encoded data stream, and is safe to
269   * call multiple times.
270   *
271   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
272   * specifies the decoder to reset.
273   *
274   * @param[in] request_id A request ID that allows the browser to associate a
275   * request to reset the decoder with a corresponding call to the
276   * <code>DecoderResetDone()</code> method on the
277   * <code>PPB_ContentDecryptor_Private</code> interface.
278   */
279  void ResetDecoder(
280      [in] PP_Instance instance,
281      [in] PP_DecryptorStreamType decoder_type,
282      [in] uint32_t request_id);
283
284  /**
285   * Decrypts encrypted_buffer, decodes it, and returns the unencrypted
286   * uncompressed (decoded) data to the browser via the
287   * <code>DeliverFrame()</code> or <code>DeliverSamples()</code> method on the
288   * <code>PPB_ContentDecryptor_Private</code> interface.
289   *
290   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
291   * specifies the decoder to use after <code>encrypted_buffer</code> is
292   * decrypted.
293   *
294   * @param[in] encrypted_buffer A <code>PP_Resource</code> corresponding to a
295   * <code>PPB_Buffer_Dev</code> resource that contains encrypted media data.
296   *
297   * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
298   * contains all auxiliary information needed for decryption of the
299   * <code>encrypted_block</code>.
300   */
301  void DecryptAndDecode(
302      [in] PP_Instance instance,
303      [in] PP_DecryptorStreamType decoder_type,
304      [in] PP_Resource encrypted_buffer,
305      [in] PP_EncryptedBlockInfo encrypted_block_info);
306};
307