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