ppapi/api/private/ppb_content_decryptor_private.idl

   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 };