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