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