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