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   * Creates a session. <code>init_data_type</code> contains the MIME type of
35   * <code>init_data</code>. <code>init_data</code> is a data buffer
36   * containing data for use in generating the request.
37   *
38   * Note: <code>CreateSession()</code> must create a web session ID and provide
39   * it to the browser via <code>SessionCreated()</code> on the
40   * <code>PPB_ContentDecryptor_Private</code> interface.
41   *
42   * @param[in] promise_id A reference for the promise that gets resolved or
43   * rejected depending upon the success or failure when creating the session.
44   *
45   * @param[in] init_data_type A <code>PP_Var</code> of type
46   * <code>PP_VARTYPE_STRING</code> containing the MIME type for init_data.
47   *
48   * @param[in] init_data A <code>PP_Var</code> of type
49   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific
50   * initialization data.
51   *
52   * @param[in] session_type A <code>PP_SessionType</code> that indicates the
53   * type of session to be created.
54   */
55  void CreateSession(
56      [in] PP_Instance instance,
57      [in] uint32_t promise_id,
58      [in] PP_Var init_data_type,
59      [in] PP_Var init_data,
60      [in] PP_SessionType session_type);
61
62  /**
63   * Loads a session whose web session ID is <code>web_session_id</code>.
64   *
65   * Note: After the session is successfully loaded, the CDM must call
66   * <code>SessionCreated()</code> with <code>web_session_id</code> on the
67   * <code>PPB_ContentDecryptor_Private</code> interface.
68   *
69   * @param[in] promise_id A reference for the promise that gets resolved or
70   * rejected depending upon the success or failure of loading the session.
71   *
72   * @param[in] web_session_id A <code>PP_Var</code> of type
73   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
74   * to load.
75   */
76  void LoadSession(
77      [in] PP_Instance instance,
78      [in] uint32_t promise_id,
79      [in] PP_Var web_session_id);
80
81  /**
82   * Provides a license or other message to the decryptor.
83   *
84   * When the CDM needs more information, it must call
85   * <code>SessionMessage()</code> on the
86   * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
87   * must notify the web application. When the CDM has finished processing
88   * <code>response</code> and needs no more information, it must call
89   * <code>SessionReady()</code> on the
90   * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
91   * must notify the web application.
92   *
93   * @param[in] promise_id A reference for the promise that gets resolved or
94   * rejected depending upon the success or failure of updating the session.
95   *
96   * @param[in] web_session_id A <code>PP_Var</code> of type
97   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
98   * to be updated.
99   *
100   * @param[in] response A <code>PP_Var</code> of type
101   * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the license or other
102   * message for the given session ID.
103   */
104  void UpdateSession(
105      [in] PP_Instance instance,
106      [in] uint32_t promise_id,
107      [in] PP_Var web_session_id,
108      [in] PP_Var response);
109
110  /**
111   * Release the specified session and related resources.
112   *
113   * @param[in] promise_id A reference for the promise that gets resolved or
114   * rejected depending upon the success or failure of releasing the session.
115   *
116   * @param[in] web_session_id A <code>PP_Var</code> of type
117   * <code>PP_VARTYPE_STRING</code> containing the web session ID of the session
118   * to be released.
119   *
120   */
121  void ReleaseSession(
122      [in] PP_Instance instance,
123      [in] uint32_t promise_id,
124      [in] PP_Var web_session_id);
125
126  /**
127   * Decrypts the block and returns the unencrypted block via
128   * <code>DeliverBlock()</code> on the
129   * <code>PPB_ContentDecryptor_Private</code> interface. The returned block
130   * contains encoded data.
131   *
132   * @param[in] resource A <code>PP_Resource</code> corresponding to a
133   * <code>PPB_Buffer_Dev</code> resource that contains an encrypted data
134   * block.
135   *
136   * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
137   * contains all auxiliary information needed for decryption of the
138   * <code>encrypted_block</code>.
139   */
140  void Decrypt(
141      [in] PP_Instance instance,
142      [in] PP_Resource encrypted_block,
143      [in] PP_EncryptedBlockInfo encrypted_block_info);
144
145 /**
146  * Initializes the audio decoder using codec and settings in
147  * <code>decoder_config</code>, and returns the result of the initialization
148  * request to the browser using the <code>DecoderInitializeDone()</code> method
149  * on the <code>PPB_ContentDecryptor_Private</code> interface.
150  *
151  * @param[in] decoder_config A <code>PP_AudioDecoderConfig</code> that
152  * contains audio decoder settings and a request ID. The request ID is passed
153  * to the <code>DecoderInitializeDone()</code> method on the
154  * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
155  * associate the result with a audio decoder initialization request.
156  *
157  * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
158  * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
159  * by some codecs. It should be set to 0 when the codec being initialized
160  * does not require it.
161  */
162  void InitializeAudioDecoder(
163      [in] PP_Instance instance,
164      [in] PP_AudioDecoderConfig decoder_config,
165      [in] PP_Resource codec_extra_data);
166
167 /**
168  * Initializes the video decoder using codec and settings in
169  * <code>decoder_config</code>, and returns the result of the initialization
170  * request to the browser using the <code>DecoderInitializeDone()</code>
171  * method on the <code>PPB_ContentDecryptor_Private</code> interface.
172  *
173  * @param[in] decoder_config A <code>PP_VideoDecoderConfig</code> that
174  * contains video decoder settings and a request ID. The request ID is passed
175  * to the <code>DecoderInitializeDone()</code> method on the
176  * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
177  * associate the result with a video decoder initialization request.
178  *
179  * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
180  * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
181  * by some codecs. It should be set to 0 when the codec being initialized
182  * does not require it.
183  */
184  void InitializeVideoDecoder(
185      [in] PP_Instance instance,
186      [in] PP_VideoDecoderConfig decoder_config,
187      [in] PP_Resource codec_extra_data);
188
189  /**
190   * De-initializes the decoder for the <code>PP_DecryptorStreamType</code>
191   * specified by <code>decoder_type</code> and sets it to an uninitialized
192   * state. The decoder can be re-initialized after de-initialization completes
193   * by calling <code>InitializeAudioDecoder</code> or
194   * <code>InitializeVideoDecoder</code>.
195   *
196   * De-initialization completion is reported to the browser using the
197   * <code>DecoderDeinitializeDone()</code> method on the
198   * <code>PPB_ContentDecryptor_Private</code> interface.
199   *
200   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
201   * specifies the decoder to de-initialize.
202   *
203   * @param[in] request_id A request ID that allows the browser to associate a
204   * request to de-initialize a decoder with the corresponding call to the
205   * <code>DecoderDeinitializeDone()</code> method on the
206   * <code>PPB_ContentDecryptor_Private</code> interface.
207   */
208  void DeinitializeDecoder(
209      [in] PP_Instance instance,
210      [in] PP_DecryptorStreamType decoder_type,
211      [in] uint32_t request_id);
212
213  /**
214   * Resets the decoder for the <code>PP_DecryptorStreamType</code> specified
215   * by <code>decoder_type</code> to an initialized clean state. Reset
216   * completion is reported to the browser using the
217   * <code>DecoderResetDone()</code> method on the
218   * <code>PPB_ContentDecryptor_Private</code> interface. This method can be
219   * used to signal a discontinuity in the encoded data stream, and is safe to
220   * call multiple times.
221   *
222   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
223   * specifies the decoder to reset.
224   *
225   * @param[in] request_id A request ID that allows the browser to associate a
226   * request to reset the decoder with a corresponding call to the
227   * <code>DecoderResetDone()</code> method on the
228   * <code>PPB_ContentDecryptor_Private</code> interface.
229   */
230  void ResetDecoder(
231      [in] PP_Instance instance,
232      [in] PP_DecryptorStreamType decoder_type,
233      [in] uint32_t request_id);
234
235  /**
236   * Decrypts encrypted_buffer, decodes it, and returns the unencrypted
237   * uncompressed (decoded) data to the browser via the
238   * <code>DeliverFrame()</code> or <code>DeliverSamples()</code> method on the
239   * <code>PPB_ContentDecryptor_Private</code> interface.
240   *
241   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
242   * specifies the decoder to use after <code>encrypted_buffer</code> is
243   * decrypted.
244   *
245   * @param[in] encrypted_buffer A <code>PP_Resource</code> corresponding to a
246   * <code>PPB_Buffer_Dev</code> resource that contains encrypted media data.
247   *
248   * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
249   * contains all auxiliary information needed for decryption of the
250   * <code>encrypted_block</code>.
251   */
252  void DecryptAndDecode(
253      [in] PP_Instance instance,
254      [in] PP_DecryptorStreamType decoder_type,
255      [in] PP_Resource encrypted_buffer,
256      [in] PP_EncryptedBlockInfo encrypted_block_info);
257};
258