ppb_content_decryptor_private.h revision 1e9bf3e0803691d0a228da41fc608347b6db4340 
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 Thu Oct 10 14:49:51 2013.
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_var.h"
19#include "ppapi/c/private/pp_content_decryptor.h"
20
21#define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_7 \
22    "PPB_ContentDecryptor_Private;0.7"
23#define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE \
24    PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_7
25
26/**
27 * @file
28 * This file defines the <code>PPB_ContentDecryptor_Private</code>
29 * interface. Note: This is a special interface, only to be used for Content
30 * Decryption Modules, not normal plugins.
31 */
32
33
34/**
35 * @addtogroup Interfaces
36 * @{
37 */
38/**
39 * <code>PPB_ContentDecryptor_Private</code> structure contains the function
40 * pointers the browser must implement to support plugins implementing the
41 * <code>PPP_ContentDecryptor_Private</code> interface. This interface provides
42 * browser side support for the Content Decryption Module (CDM) for v0.1 of the
43 * proposed Encrypted Media Extensions: http://goo.gl/rbdnR
44 */
45struct PPB_ContentDecryptor_Private_0_7 {
46  /**
47   * A key has been added as the result of a call to the <code>AddKey()</code>
48   * method on the <code>PPP_ContentDecryptor_Private</code> interface.
49   *
50   * Note: The above describes the most simple case. Depending on the key
51   * system, a series of <code>KeyMessage()</code> calls from the CDM will be
52   * sent to the browser, and then on to the web application. The web
53   * application must then provide more data to the CDM by directing the browser
54   * to pass the data to the CDM via calls to <code>AddKey()</code> on the
55   * <code>PPP_ContentDecryptor_Private</code> interface.
56   * The CDM must call <code>KeyAdded()</code> when the sequence is completed,
57   * and, in response, the browser must notify the web application.
58   *
59   * @param[in] key_system A <code>PP_Var</code> of type
60   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
61   *
62   * @param[in] session_id A <code>PP_Var</code> of type
63   * <code>PP_VARTYPE_STRING</code> containing the session ID.
64   */
65  void (*KeyAdded)(PP_Instance instance,
66                   struct PP_Var key_system,
67                   struct PP_Var session_id);
68  /**
69   * A message or request has been generated for key_system in the CDM, and
70   * must be sent to the web application.
71   *
72   * For example, when the browser invokes <code>GenerateKeyRequest()</code>
73   * on the <code>PPP_ContentDecryptor_Private</code> interface, the plugin
74   * must send a key message containing the key request.
75   *
76   * Note that <code>KeyMessage()</code> can be used for purposes other than
77   * responses to <code>GenerateKeyRequest()</code> calls. See also the text
78   * in the comment for <code>KeyAdded()</code>, which describes a sequence of
79   * <code>AddKey()</code> and <code>KeyMessage()</code> calls required to
80   * prepare for decryption.
81   *
82   * @param[in] key_system A <code>PP_Var</code> of type
83   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
84   *
85   * @param[in] session_id A <code>PP_Var</code> of type
86   * <code>PP_VARTYPE_STRING</code> containing the session ID.
87   *
88   * @param[in] message A <code>PP_Var</code> of type
89   * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the message.
90   *
91   * @param[in] default_url A <code>PP_Var</code> of type
92   * <code>PP_VARTYPE_STRING</code> containing the default URL for the message.
93   */
94  void (*KeyMessage)(PP_Instance instance,
95                     struct PP_Var key_system,
96                     struct PP_Var session_id,
97                     struct PP_Var message,
98                     struct PP_Var default_url);
99  /**
100   * An error occurred in a <code>PPP_ContentDecryptor_Private</code> method,
101   * or within the plugin implementing the interface.
102   *
103   * @param[in] key_system A <code>PP_Var</code> of type
104   * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
105   *
106   * @param[in] session_id A <code>PP_Var</code> of type
107   * <code>PP_VARTYPE_STRING</code> containing the session ID.
108   *
109   * @param[in] media_error A MediaKeyError.
110   *
111   * @param[in] system_error A system error code.
112   */
113  void (*KeyError)(PP_Instance instance,
114                   struct PP_Var key_system,
115                   struct PP_Var session_id,
116                   int32_t media_error,
117                   int32_t system_code);
118  /**
119   * Called after the <code>Decrypt()</code> method on the
120   * <code>PPP_ContentDecryptor_Private</code> interface completes to
121   * deliver decrypted_block to the browser for decoding and rendering.
122   *
123   * The plugin must not hold a reference to the encrypted buffer resource
124   * provided to <code>Decrypt()</code> when it calls this method. The browser
125   * will reuse the buffer in a subsequent <code>Decrypt()</code> call.
126   *
127   * @param[in] decrypted_block A <code>PP_Resource</code> corresponding to a
128   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
129   * block.
130   *
131   * @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
132   * contains the result code and tracking info associated with the
133   * <code>decrypted_block</code>.
134   */
135  void (*DeliverBlock)(
136      PP_Instance instance,
137      PP_Resource decrypted_block,
138      const struct PP_DecryptedBlockInfo* decrypted_block_info);
139  /**
140   * Called after the <code>InitializeAudioDecoder()</code> or
141   * <code>InitializeVideoDecoder()</code> method on the
142   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
143   * decoder initialization status to the browser.
144   *
145   * @param[in] success A <code>PP_Bool</code> that is set to
146   * <code>PP_TRUE</code> when the decoder initialization request associated
147   * with <code>request_id</code> was successful.
148   *
149   * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> identifying
150   * the decoder type for which this initialization status response was sent.
151   *
152   * @param[in] request_id The <code>request_id</code> value passed to
153   * <code>InitializeAudioDecoder</code> or <code>InitializeVideoDecoder</code>
154   * in <code>PP_AudioDecoderConfig</code> or
155   * <code>PP_VideoDecoderConfig</code>.
156   */
157  void (*DecoderInitializeDone)(PP_Instance instance,
158                                PP_DecryptorStreamType decoder_type,
159                                uint32_t request_id,
160                                PP_Bool success);
161  /**
162   * Called after the <code>DeinitializeDecoder()</code> method on the
163   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
164   * decoder de-initialization completion to the browser.
165   *
166   * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
167   * <code>DeinitializeDecoder()</code>.
168   *
169   * @param[in] request_id The <code>request_id</code> value passed to
170   * <code>DeinitializeDecoder()</code>.
171   */
172  void (*DecoderDeinitializeDone)(PP_Instance instance,
173                                  PP_DecryptorStreamType decoder_type,
174                                  uint32_t request_id);
175  /**
176   * Called after the <code>ResetDecoder()</code> method on the
177   * <code>PPP_ContentDecryptor_Private</code> interface completes to report
178   * decoder reset completion to the browser.
179   *
180   * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
181   * <code>ResetDecoder()</code>.
182   *
183   * @param[in] request_id The <code>request_id</code> value passed to
184   * <code>ResetDecoder()</code>.
185   */
186  void (*DecoderResetDone)(PP_Instance instance,
187                           PP_DecryptorStreamType decoder_type,
188                           uint32_t request_id);
189  /**
190   * Called after the <code>DecryptAndDecode()</code> method on the
191   * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
192   * a decrypted and decoded video frame to the browser for rendering.
193   *
194   * The plugin must not hold a reference to the encrypted buffer resource
195   * provided to <code>DecryptAndDecode()</code> when it calls this method. The
196   * browser will reuse the buffer in a subsequent
197   * <code>DecryptAndDecode()</code> call.
198   *
199   * @param[in] decrypted_frame A <code>PP_Resource</code> corresponding to a
200   * <code>PPB_Buffer_Dev</code> resource that contains a video frame.
201   *
202   * @param[in] decrypted_frame_info A <code>PP_DecryptedFrameInfo</code> that
203   * contains the result code, tracking info, and buffer format associated with
204   * <code>decrypted_frame</code>.
205   */
206  void (*DeliverFrame)(
207      PP_Instance instance,
208      PP_Resource decrypted_frame,
209      const struct PP_DecryptedFrameInfo* decrypted_frame_info);
210  /**
211   * Called after the <code>DecryptAndDecode()</code> method on the
212   * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
213   * a buffer of decrypted and decoded audio samples to the browser for
214   * rendering.
215   *
216   * The plugin must not hold a reference to the encrypted buffer resource
217   * provided to <code>DecryptAndDecode()</code> when it calls this method. The
218   * browser will reuse the buffer in a subsequent
219   * <code>DecryptAndDecode()</code> call.
220   *
221   * <code>audio_frames</code> can contain multiple audio output buffers. Each
222   * buffer is serialized in this format:
223   *
224   * |<------------------- serialized audio buffer ------------------->|
225   * | int64_t timestamp | int64_t length | length bytes of audio data |
226   *
227   * For example, with three audio output buffers, |audio_frames| will look
228   * like this:
229   *
230   * |<---------------- audio_frames ------------------>|
231   * | audio buffer 0 | audio buffer 1 | audio buffer 2 |
232   *
233   * @param[in] audio_frames A <code>PP_Resource</code> corresponding to a
234   * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
235   * of decoded audio samples.
236   *
237   * @param[in] decrypted_sample_info A <code>PP_DecryptedSampleInfo</code> that
238   * contains the tracking info and result code associated with the decrypted
239   * samples.
240   */
241  void (*DeliverSamples)(
242      PP_Instance instance,
243      PP_Resource audio_frames,
244      const struct PP_DecryptedSampleInfo* decrypted_sample_info);
245};
246
247typedef struct PPB_ContentDecryptor_Private_0_7 PPB_ContentDecryptor_Private;
248/**
249 * @}
250 */
251
252#endif  /* PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_ */
253
254