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/* From private/ppb_content_decryptor_private.idl,
7 *   modified Mon Aug 25 13:52:39 2014.
8 */
9
10#ifndef PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_
11#define PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_
12
13#include "ppapi/c/pp_bool.h"
14#include "ppapi/c/pp_instance.h"
15#include "ppapi/c/pp_macros.h"
16#include "ppapi/c/pp_resource.h"
17#include "ppapi/c/pp_stdint.h"
18#include "ppapi/c/pp_time.h"
19#include "ppapi/c/pp_var.h"
20#include "ppapi/c/private/pp_content_decryptor.h"
21
22#define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_12 \
23    "PPB_ContentDecryptor_Private;0.12"
24#define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE \
25    PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_12
26
27/**
28 * @file
29 * This file defines the <code>PPB_ContentDecryptor_Private</code>
30 * interface. Note: This is a special interface, only to be used for Content
31 * Decryption Modules, not normal plugins.
32 */
33
34
35/**
36 * @addtogroup Interfaces
37 * @{
38 */
39/**
40 * <code>PPB_ContentDecryptor_Private</code> structure contains the function
41 * pointers the browser must implement to support plugins implementing the
42 * <code>PPP_ContentDecryptor_Private</code> interface. This interface provides
43 * browser side support for the Content Decryption Module (CDM) for Encrypted
44 * Media Extensions: http://www.w3.org/TR/encrypted-media/
45 */
46struct PPB_ContentDecryptor_Private_0_12 {
47  /**
48   * A promise has been resolved by the CDM.
49   *
50   * @param[in] promise_id Identifies the promise that the CDM resolved.
51   */
52  void (*PromiseResolved)(PP_Instance instance, uint32_t promise_id);
53  /**
54   * A promise that resulted in a new session has been resolved by the CDM.
55   *
56   * @param[in] promise_id Identifies the promise that the CDM resolved.
57   *
58   * @param[in] web_session_id A <code>PP_Var</code> of type
59   * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute.
60   */
61  void (*PromiseResolvedWithSession)(PP_Instance instance,
62                                     uint32_t promise_id,
63                                     struct PP_Var web_session_id);
64  /**
65   * A promise that returns a set of key IDs has been resolved by the CDM.
66   *
67   * @param[in] promise_id Identifies the promise that the CDM resolved.
68   *
69   * @param[in] key_ids A <code>PP_Var</code> of type
70   * <code>PP_VARTYPE_ARRAY</code> containing elements of type
71   * <code>PP_VARTYPE_ARRAYBUFFER</code> that are the session's usable key IDs.
72   */
73  void (*PromiseResolvedWithKeyIds)(PP_Instance instance,
74                                    uint32_t promise_id,
75                                    struct PP_Var key_ids_array);
76  /**
77   * A promise has been rejected by the CDM due to an error.
78   *
79   * @param[in] promise_id Identifies the promise that the CDM rejected.
80   *
81   * @param[in] exception_code A <code>PP_CdmExceptionCode</code> containing
82   * the exception code.
83   *
84   * @param[in] system_code A system error code.
85   *
86   * @param[in] error_description A <code>PP_Var</code> of type
87   * <code>PP_VARTYPE_STRING</code> containing the error description.
88   */
89  void (*PromiseRejected)(PP_Instance instance,
90                          uint32_t promise_id,
91                          PP_CdmExceptionCode exception_code,
92                          uint32_t system_code,
93                          struct PP_Var error_description);
94  /**
95   * A message or request has been generated for key_system in the CDM, and
96   * must be sent to the web application.
97   *
98   * For example, when the browser invokes <code>CreateSession()</code>
99   * on the <code>PPP_ContentDecryptor_Private</code> interface, the plugin
100   * must send a message containing the license request.
101   *
102   * Note that <code>SessionMessage()</code> can be used for purposes other than
103   * responses to <code>CreateSession()</code> calls. See also the text
104   * in the comment for <code>SessionReady()</code>, which describes a sequence
105   * of <code>UpdateSession()</code> and <code>SessionMessage()</code> calls
106   * required to prepare for decryption.
107   *
108   * @param[in] web_session_id A <code>PP_Var</code> of type
109   * <code>PP_VARTYPE_STRING</code> containing the ID of a session for
110   * which this message is intended.
111   *
112   * @param[in] message A <code>PP_Var</code> of type
113   * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the message.
114   *
115   * @param[in] destination_url A <code>PP_Var</code> of type
116   * <code>PP_VARTYPE_STRING</code> containing the destination URL for the
117   * message.
118   */
119  void (*SessionMessage)(PP_Instance instance,
120                         struct PP_Var web_session_id,
121                         struct PP_Var message,
122                         struct PP_Var destination_url);
123  /**
124   * The keys for a session have changed.
125   *
126   * @param[in] web_session_id A <code>PP_Var</code> of type
127   * <code>PP_VARTYPE_STRING</code> containing the ID of the session that has
128   * a change in keys.
129   *
130   * @param[in] has_additional_usable_key A <code>PP_Bool</code> indicating if
131   * a new usable key has been added.
132   */
133  void (*SessionKeysChange)(PP_Instance instance,
134                            struct PP_Var web_session_id,
135                            PP_Bool has_additional_usable_key);
136  /**
137   * The expiration time for a session has changed.
138   *
139   * @param[in] web_session_id A <code>PP_Var</code> of type
140   * <code>PP_VARTYPE_STRING</code> containing the ID of the session that has
141   * a new expiration time.
142   *
143   * @param[in] new_expiry_time A <code>PP_Time</code> indicating the new
144   * expiry time of the session. The value is defined as the number of seconds
145   * since the Epoch (00:00:00 UTC, January 1, 1970).
146   */
147  void (*SessionExpirationChange)(PP_Instance instance,
148                                  struct PP_Var web_session_id,
149                                  PP_Time new_expiry_time);
150  /**
151   * The session is now ready to decrypt the media stream.
152   *
153   * Note: The above describes the most simple case. Depending on the key
154   * system, a series of <code>SessionMessage()</code> calls from the CDM will
155   * be sent to the browser, and then on to the web application. The web
156   * application must then provide more data to the CDM by directing the browser
157   * to pass the data to the CDM via calls to <code>UpdateSession()</code> on
158   * the <code>PPP_ContentDecryptor_Private</code> interface.
159   * The CDM must call <code>SessionReady()</code> when the sequence is
160   * completed, and, in response, the browser must notify the web application.
161   *
162   * @param[in] web_session_id A <code>PP_Var</code> of type
163   * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
164   * the session that is now ready.
165   */
166  void (*SessionReady)(PP_Instance instance, struct PP_Var web_session_id);
167  /**
168   * The session has been closed as the result of a call to the
169   * <code>ReleaseSession()</code> method on the
170   * <code>PPP_ContentDecryptor_Private</code> interface, or due to other
171   * factors as determined by the CDM.
172   *
173   * @param[in] web_session_id A <code>PP_Var</code> of type
174   * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
175   * the session that is now closed.
176   */
177  void (*SessionClosed)(PP_Instance instance, struct PP_Var web_session_id);
178  /**
179   * An error occurred in a <code>PPP_ContentDecryptor_Private</code> method,
180   * or within the plugin implementing the interface.
181   *
182   * @param[in] web_session_id A <code>PP_Var</code> of type
183   * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
184   * the session that caused the error.
185   *
186   * @param[in] exception_code A <code>PP_CdmExceptionCode</code> containing
187   * the exception code.
188   *
189   * @param[in] system_code A system error code.
190   *
191   * @param[in] error_description A <code>PP_Var</code> of type
192   * <code>PP_VARTYPE_STRING</code> containing the error description.
193   */
194  void (*SessionError)(PP_Instance instance,
195                       struct PP_Var web_session_id,
196                       PP_CdmExceptionCode exception_code,
197                       uint32_t system_code,
198                       struct PP_Var error_description);
199  /**
200   * Called after the <code>Decrypt()</code> method on the
201   * <code>PPP_ContentDecryptor_Private</code> interface completes to
202   * deliver decrypted_block to the browser for decoding and rendering.
203   *
204   * The plugin must not hold a reference to the encrypted buffer resource
205   * provided to <code>Decrypt()</code> when it calls this method. The browser
206   * will reuse the buffer in a subsequent <code>Decrypt()</code> call.
207   *
208   * @param[in] decrypted_block A <code>PP_Resource</code> corresponding to a
209   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
210   * block.
211   *
212   * @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
213   * contains the result code and tracking info associated with the
214   * <code>decrypted_block</code>.
215   */
216  void (*DeliverBlock)(
217      PP_Instance instance,
218      PP_Resource decrypted_block,
219      const struct PP_DecryptedBlockInfo* decrypted_block_info);
220  /**
221   * Called after the <code>InitializeAudioDecoder()</code> or
222   * <code>InitializeVideoDecoder()</code> method on the
223   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
224   * decoder initialization status to the browser.
225   *
226   * @param[in] success A <code>PP_Bool</code> that is set to
227   * <code>PP_TRUE</code> when the decoder initialization request associated
228   * with <code>request_id</code> was successful.
229   *
230   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> identifying
231   * the decoder type for which this initialization status response was sent.
232   *
233   * @param[in] request_id The <code>request_id</code> value passed to
234   * <code>InitializeAudioDecoder</code> or <code>InitializeVideoDecoder</code>
235   * in <code>PP_AudioDecoderConfig</code> or
236   * <code>PP_VideoDecoderConfig</code>.
237   */
238  void (*DecoderInitializeDone)(PP_Instance instance,
239                                PP_DecryptorStreamType decoder_type,
240                                uint32_t request_id,
241                                PP_Bool success);
242  /**
243   * Called after the <code>DeinitializeDecoder()</code> method on the
244   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
245   * decoder de-initialization completion to the browser.
246   *
247   * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
248   * <code>DeinitializeDecoder()</code>.
249   *
250   * @param[in] request_id The <code>request_id</code> value passed to
251   * <code>DeinitializeDecoder()</code>.
252   */
253  void (*DecoderDeinitializeDone)(PP_Instance instance,
254                                  PP_DecryptorStreamType decoder_type,
255                                  uint32_t request_id);
256  /**
257   * Called after the <code>ResetDecoder()</code> method on the
258   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
259   * decoder reset completion to the browser.
260   *
261   * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
262   * <code>ResetDecoder()</code>.
263   *
264   * @param[in] request_id The <code>request_id</code> value passed to
265   * <code>ResetDecoder()</code>.
266   */
267  void (*DecoderResetDone)(PP_Instance instance,
268                           PP_DecryptorStreamType decoder_type,
269                           uint32_t request_id);
270  /**
271   * Called after the <code>DecryptAndDecode()</code> method on the
272   * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
273   * a decrypted and decoded video frame to the browser for rendering.
274   *
275   * The plugin must not hold a reference to the encrypted buffer resource
276   * provided to <code>DecryptAndDecode()</code> when it calls this method. The
277   * browser will reuse the buffer in a subsequent
278   * <code>DecryptAndDecode()</code> call.
279   *
280   * @param[in] decrypted_frame A <code>PP_Resource</code> corresponding to a
281   * <code>PPB_Buffer_Dev</code> resource that contains a video frame.
282   *
283   * @param[in] decrypted_frame_info A <code>PP_DecryptedFrameInfo</code> that
284   * contains the result code, tracking info, and buffer format associated with
285   * <code>decrypted_frame</code>.
286   */
287  void (*DeliverFrame)(
288      PP_Instance instance,
289      PP_Resource decrypted_frame,
290      const struct PP_DecryptedFrameInfo* decrypted_frame_info);
291  /**
292   * Called after the <code>DecryptAndDecode()</code> method on the
293   * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
294   * a buffer of decrypted and decoded audio samples to the browser for
295   * rendering.
296   *
297   * The plugin must not hold a reference to the encrypted buffer resource
298   * provided to <code>DecryptAndDecode()</code> when it calls this method. The
299   * browser will reuse the buffer in a subsequent
300   * <code>DecryptAndDecode()</code> call.
301   *
302   * <code>audio_frames</code> can contain multiple audio output buffers. Each
303   * buffer is serialized in this format:
304   *
305   * |<------------------- serialized audio buffer ------------------->|
306   * | int64_t timestamp | int64_t length | length bytes of audio data |
307   *
308   * For example, with three audio output buffers, |audio_frames| will look
309   * like this:
310   *
311   * |<---------------- audio_frames ------------------>|
312   * | audio buffer 0 | audio buffer 1 | audio buffer 2 |
313   *
314   * @param[in] audio_frames A <code>PP_Resource</code> corresponding to a
315   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
316   * of decoded audio samples.
317   *
318   * @param[in] decrypted_sample_info A <code>PP_DecryptedSampleInfo</code> that
319   * contains the tracking info and result code associated with the decrypted
320   * samples.
321   */
322  void (*DeliverSamples)(
323      PP_Instance instance,
324      PP_Resource audio_frames,
325      const struct PP_DecryptedSampleInfo* decrypted_sample_info);
326};
327
328typedef struct PPB_ContentDecryptor_Private_0_12 PPB_ContentDecryptor_Private;
329/**
330 * @}
331 */
332
333#endif  /* PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_ */
334
335