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   M24 = 0.6
  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 v0.1 of the proposed Encrypted Media Extensions:
  20  * http://goo.gl/rbdnR
  21  */
  22 interface PPP_ContentDecryptor_Private {
  23   /**
  24    * Generates a key request. key_system specifies the key or licensing system
  25    * to use. type contains the MIME type of init_data. init_data is a data
  26    * buffer containing data for use in generating the request.
  27    *
  28    * Note: <code>GenerateKeyRequest()</code> must create the session ID used in
  29    * other methods on this interface. The session ID must be provided to the
  30    * browser by the CDM via <code>KeyMessage()</code> on the
  31    * <code>PPB_ContentDecryptor_Private</code> interface.
  32    *
  33    * @param[in] key_system A <code>PP_Var</code> of type
  34    * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
  35    *
  36    * @param[in] type A <code>PP_Var</code> of type
  37    * <code>PP_VARTYPE_STRING</code> containing the MIME type for init_data.
  38    *
  39    * @param[in] init_data A <code>PP_Var</code> of type
  40    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific
  41    * initialization data.
  42    */
  43   void GenerateKeyRequest(
  44       [in] PP_Instance instance,
  45       [in] PP_Var key_system,
  46       [in] PP_Var type,
  47       [in] PP_Var init_data);
  48
  49   /**
  50    * Provides a key or license to the decryptor for decrypting media data.
  51    *
  52    * When the CDM needs more information to complete addition of the key it
  53    * will call <code>KeyMessage()</code> on the
  54    * <code>PPB_ContentDecryptor_Private</code> interface, which the browser
  55    * passes to the application. When the key is ready to use, the CDM
  56    * must call call <code>KeyAdded()</code> on the
  57    * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
  58    * must notify the web application.
  59    *
  60    * @param[in] session_id A <code>PP_Var</code> of type
  61    * <code>PP_VARTYPE_STRING</code> containing the session ID.
  62    *
  63    * @param[in] key A <code>PP_Var</code> of type
  64    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the decryption key, license,
  65    * or other message for the given session ID.
  66    *
  67    * @param[in] init_data A <code>PP_Var</code> of type
  68    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific
  69    * initialization data.
  70    */
  71   void AddKey(
  72       [in] PP_Instance instance,
  73       [in] PP_Var session_id,
  74       [in] PP_Var key,
  75       [in] PP_Var init_data);
  76
  77   /**
  78    * Cancels a pending key request for the specified session ID.
  79    *
  80    * @param[in] session_id A <code>PP_Var</code> of type
  81    * <code>PP_VARTYPE_STRING</code> containing the session ID.
  82    */
  83   void CancelKeyRequest(
  84       [in] PP_Instance instance,
  85       [in] PP_Var session_id);
  86
  87   /**
  88    * Decrypts the block and returns the unencrypted block via
  89    * <code>DeliverBlock()</code> on the
  90    * <code>PPB_ContentDecryptor_Private</code> interface. The returned block
  91    * contains encoded data.
  92    *
  93    * @param[in] resource A <code>PP_Resource</code> corresponding to a
  94    * <code>PPB_Buffer_Dev</code> resource that contains an encrypted data
  95    * block.
  96    *
  97    * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
  98    * contains all auxiliary information needed for decryption of the
  99    * <code>encrypted_block</code>.
 100    */
 101   void Decrypt(
 102       [in] PP_Instance instance,
 103       [in] PP_Resource encrypted_block,
 104       [in] PP_EncryptedBlockInfo encrypted_block_info);
 105
 106  /**
 107   * Initializes the audio decoder using codec and settings in
 108   * <code>decoder_config</code>, and returns the result of the initialization
 109   * request to the browser using the <code>DecoderInitializeDone()</code> method
 110   * on the <code>PPB_ContentDecryptor_Private</code> interface.
 111   *
 112   * @param[in] decoder_config A <code>PP_AudioDecoderConfig</code> that
 113   * contains audio decoder settings and a request ID. The request ID is passed
 114   * to the <code>DecoderInitializeDone()</code> method on the
 115   * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
 116   * associate the result with a audio decoder initialization request.
 117   *
 118   * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
 119   * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
 120   * by some codecs. It should be set to 0 when the codec being initialized
 121   * does not require it.
 122   */
 123   void InitializeAudioDecoder(
 124       [in] PP_Instance instance,
 125       [in] PP_AudioDecoderConfig decoder_config,
 126       [in] PP_Resource codec_extra_data);
 127
 128  /**
 129   * Initializes the video decoder using codec and settings in
 130   * <code>decoder_config</code>, and returns the result of the initialization
 131   * request to the browser using the <code>DecoderInitializeDone()</code>
 132   * method on the <code>PPB_ContentDecryptor_Private</code> interface.
 133   *
 134   * @param[in] decoder_config A <code>PP_VideoDecoderConfig</code> that
 135   * contains video decoder settings and a request ID. The request ID is passed
 136   * to the <code>DecoderInitializeDone()</code> method on the
 137   * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
 138   * associate the result with a video decoder initialization request.
 139   *
 140   * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
 141   * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
 142   * by some codecs. It should be set to 0 when the codec being initialized
 143   * does not require it.
 144   */
 145   void InitializeVideoDecoder(
 146       [in] PP_Instance instance,
 147       [in] PP_VideoDecoderConfig decoder_config,
 148       [in] PP_Resource codec_extra_data);
 149
 150   /**
 151    * De-initializes the decoder for the <code>PP_DecryptorStreamType</code>
 152    * specified by <code>decoder_type</code> and sets it to an uninitialized
 153    * state. The decoder can be re-initialized after de-initialization completes
 154    * by calling <code>InitializeAudioDecoder</code> or
 155    * <code>InitializeVideoDecoder</code>.
 156    *
 157    * De-initialization completion is reported to the browser using the
 158    * <code>DecoderDeinitializeDone()</code> method on the
 159    * <code>PPB_ContentDecryptor_Private</code> interface.
 160    *
 161    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 162    * specifies the decoder to de-initialize.
 163    *
 164    * @param[in] request_id A request ID that allows the browser to associate a
 165    * request to de-initialize a decoder with the corresponding call to the
 166    * <code>DecoderDeinitializeDone()</code> method on the
 167    * <code>PPB_ContentDecryptor_Private</code> interface.
 168    */
 169   void DeinitializeDecoder(
 170       [in] PP_Instance instance,
 171       [in] PP_DecryptorStreamType decoder_type,
 172       [in] uint32_t request_id);
 173
 174   /**
 175    * Resets the decoder for the <code>PP_DecryptorStreamType</code> specified
 176    * by <code>decoder_type</code> to an initialized clean state. Reset
 177    * completion is reported to the browser using the
 178    * <code>DecoderResetDone()</code> method on the
 179    * <code>PPB_ContentDecryptor_Private</code> interface. This method can be
 180    * used to signal a discontinuity in the encoded data stream, and is safe to
 181    * call multiple times.
 182    *
 183    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 184    * specifies the decoder to reset.
 185    *
 186    * @param[in] request_id A request ID that allows the browser to associate a
 187    * request to reset the decoder with a corresponding call to the
 188    * <code>DecoderResetDone()</code> method on the
 189    * <code>PPB_ContentDecryptor_Private</code> interface.
 190    */
 191   void ResetDecoder(
 192       [in] PP_Instance instance,
 193       [in] PP_DecryptorStreamType decoder_type,
 194       [in] uint32_t request_id);
 195
 196   /**
 197    * Decrypts encrypted_buffer, decodes it, and returns the unencrypted
 198    * uncompressed (decoded) data to the browser via the
 199    * <code>DeliverFrame()</code> or <code>DeliverSamples()</code> method on the
 200    * <code>PPB_ContentDecryptor_Private</code> interface.
 201    *
 202    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 203    * specifies the decoder to use after <code>encrypted_buffer</code> is
 204    * decrypted.
 205    *
 206    * @param[in] encrypted_buffer A <code>PP_Resource</code> corresponding to a
 207    * <code>PPB_Buffer_Dev</code> resource that contains encrypted media data.
 208    *
 209    * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
 210    * contains all auxiliary information needed for decryption of the
 211    * <code>encrypted_block</code>.
 212    */
 213   void DecryptAndDecode(
 214       [in] PP_Instance instance,
 215       [in] PP_DecryptorStreamType decoder_type,
 216       [in] PP_Resource encrypted_buffer,
 217       [in] PP_EncryptedBlockInfo encrypted_block_info);
 218 };