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