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   M43 = 0.14
  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    * @param[in] allow_distinctive_identifier Inform the CDM that it may use a
  29    * distinctive identifier.
  30    * @param[in] allow_persistent_state Inform the CDM that it may use persistent
  31    * state.
  32    */
  33   void Initialize(
  34       [in] PP_Instance instance,
  35       [in] PP_Var key_system,
  36       [in] PP_Bool allow_distinctive_identifier,
  37       [in] PP_Bool allow_persistent_state);
  38
  39   /**
  40    * Provides a server certificate to be used to encrypt messages to the
  41    * license server.
  42    *
  43    * @param[in] promise_id A reference for the promise that gets resolved or
  44    * rejected depending upon the success or failure of setting the certificate.
  45    *
  46    * @param[in] server_certificate A <code>PP_Var</code> of type
  47    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the certificate to be used.
  48    */
  49   void SetServerCertificate(
  50       [in] PP_Instance instance,
  51       [in] uint32_t promise_id,
  52       [in] PP_Var server_certificate);
  53
  54   /**
  55    * Creates a session and subsequently generates a request for a license.
  56    * <code>init_data_type</code> contains the MIME type of
  57    * <code>init_data</code>. <code>init_data</code> is a data buffer
  58    * containing data for use in generating the request.
  59    *
  60    * Note: <code>CreateSessionAndGenerateRequest()</code> must create a
  61    * session ID and provide it to the browser via <code>SessionCreated()</code>
  62    * on the <code>PPB_ContentDecryptor_Private</code> interface.
  63    *
  64    * @param[in] promise_id A reference for the promise that gets resolved or
  65    * rejected depending upon the success or failure when creating the session.
  66    *
  67    * @param[in] session_type A <code>PP_SessionType</code> that indicates the
  68    * type of session to be created.
  69    *
  70    * @param[in] init_data_type A <code>PP_InitDataType</code> that indicates
  71    * the Initialization Data Type for init_data.
  72    *
  73    * @param[in] init_data A <code>PP_Var</code> of type
  74    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing container specific
  75    * initialization data.
  76    */
  77   void CreateSessionAndGenerateRequest(
  78       [in] PP_Instance instance,
  79       [in] uint32_t promise_id,
  80       [in] PP_SessionType session_type,
  81       [in] PP_InitDataType init_data_type,
  82       [in] PP_Var init_data);
  83
  84   /**
  85    * Loads a session whose session ID is <code>session_id</code>.
  86    *
  87    * Note: After the session is successfully loaded, the CDM must call
  88    * <code>SessionCreated()</code> with <code>session_id</code> on the
  89    * <code>PPB_ContentDecryptor_Private</code> interface.
  90    *
  91    * @param[in] promise_id A reference for the promise that gets resolved or
  92    * rejected depending upon the success or failure of loading the session.
  93    *
  94    * @param[in] session_type A <code>PP_SessionType</code> that indicates the
  95    * type of session to be loaded.
  96    *
  97    * @param[in] session_id A <code>PP_Var</code> of type
  98    * <code>PP_VARTYPE_STRING</code> containing the session ID of the session
  99    * to load.
 100    */
 101   void LoadSession(
 102       [in] PP_Instance instance,
 103       [in] uint32_t promise_id,
 104       [in] PP_SessionType session_type,
 105       [in] PP_Var session_id);
 106
 107   /**
 108    * Provides a license or other message to the decryptor.
 109    *
 110    * When the CDM needs more information, it must call
 111    * <code>SessionMessage()</code> on the
 112    * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
 113    * must notify the web application. When the CDM has finished processing
 114    * <code>response</code> and needs no more information, it must call
 115    * <code>SessionReady()</code> on the
 116    * <code>PPB_ContentDecryptor_Private</code> interface, and the browser
 117    * must notify the web application.
 118    *
 119    * @param[in] promise_id A reference for the promise that gets resolved or
 120    * rejected depending upon the success or failure of updating the session.
 121    *
 122    * @param[in] session_id A <code>PP_Var</code> of type
 123    * <code>PP_VARTYPE_STRING</code> containing the session ID of the session
 124    * to be updated.
 125    *
 126    * @param[in] response A <code>PP_Var</code> of type
 127    * <code>PP_VARTYPE_ARRAYBUFFER</code> containing the license or other
 128    * message for the given session ID.
 129    */
 130   void UpdateSession(
 131       [in] PP_Instance instance,
 132       [in] uint32_t promise_id,
 133       [in] PP_Var session_id,
 134       [in] PP_Var response);
 135
 136   /**
 137    * Close the specified session and related resources.
 138    *
 139    * @param[in] promise_id A reference for the promise that gets resolved or
 140    * rejected depending upon the success or failure of closing the session.
 141    *
 142    * @param[in] session_id A <code>PP_Var</code> of type
 143    * <code>PP_VARTYPE_STRING</code> containing the session ID of the session
 144    * to be closed.
 145    *
 146    */
 147   void CloseSession(
 148       [in] PP_Instance instance,
 149       [in] uint32_t promise_id,
 150       [in] PP_Var session_id);
 151
 152   /**
 153    * Remove stored data associated with this session.
 154    *
 155    * @param[in] promise_id A reference for the promise that gets resolved or
 156    * rejected depending upon the success or failure of removing the session
 157    * data.
 158    *
 159    * @param[in] session_id A <code>PP_Var</code> of type
 160    * <code>PP_VARTYPE_STRING</code> containing the session ID of the session
 161    * to be removed.
 162    *
 163    */
 164   void RemoveSession(
 165       [in] PP_Instance instance,
 166       [in] uint32_t promise_id,
 167       [in] PP_Var session_id);
 168
 169   /**
 170    * Decrypts the block and returns the unencrypted block via
 171    * <code>DeliverBlock()</code> on the
 172    * <code>PPB_ContentDecryptor_Private</code> interface. The returned block
 173    * contains encoded data.
 174    *
 175    * @param[in] resource A <code>PP_Resource</code> corresponding to a
 176    * <code>PPB_Buffer_Dev</code> resource that contains an encrypted data
 177    * block.
 178    *
 179    * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
 180    * contains all auxiliary information needed for decryption of the
 181    * <code>encrypted_block</code>.
 182    */
 183   void Decrypt(
 184       [in] PP_Instance instance,
 185       [in] PP_Resource encrypted_block,
 186       [in] PP_EncryptedBlockInfo encrypted_block_info);
 187
 188  /**
 189   * Initializes the audio decoder using codec and settings in
 190   * <code>decoder_config</code>, and returns the result of the initialization
 191   * request to the browser using the <code>DecoderInitializeDone()</code> method
 192   * on the <code>PPB_ContentDecryptor_Private</code> interface.
 193   *
 194   * @param[in] decoder_config A <code>PP_AudioDecoderConfig</code> that
 195   * contains audio decoder settings and a request ID. The request ID is passed
 196   * to the <code>DecoderInitializeDone()</code> method on the
 197   * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
 198   * associate the result with a audio decoder initialization request.
 199   *
 200   * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
 201   * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
 202   * by some codecs. It should be set to 0 when the codec being initialized
 203   * does not require it.
 204   */
 205   void InitializeAudioDecoder(
 206       [in] PP_Instance instance,
 207       [in] PP_AudioDecoderConfig decoder_config,
 208       [in] PP_Resource codec_extra_data);
 209
 210  /**
 211   * Initializes the video decoder using codec and settings in
 212   * <code>decoder_config</code>, and returns the result of the initialization
 213   * request to the browser using the <code>DecoderInitializeDone()</code>
 214   * method on the <code>PPB_ContentDecryptor_Private</code> interface.
 215   *
 216   * @param[in] decoder_config A <code>PP_VideoDecoderConfig</code> that
 217   * contains video decoder settings and a request ID. The request ID is passed
 218   * to the <code>DecoderInitializeDone()</code> method on the
 219   * <code>PPB_ContentDecryptor_Private</code> interface to allow clients to
 220   * associate the result with a video decoder initialization request.
 221   *
 222   * @param[in] codec_extra_data A <code>PP_Resource</code> corresponding to a
 223   * <code>PPB_Buffer_Dev</code> resource containing codec setup data required
 224   * by some codecs. It should be set to 0 when the codec being initialized
 225   * does not require it.
 226   */
 227   void InitializeVideoDecoder(
 228       [in] PP_Instance instance,
 229       [in] PP_VideoDecoderConfig decoder_config,
 230       [in] PP_Resource codec_extra_data);
 231
 232   /**
 233    * De-initializes the decoder for the <code>PP_DecryptorStreamType</code>
 234    * specified by <code>decoder_type</code> and sets it to an uninitialized
 235    * state. The decoder can be re-initialized after de-initialization completes
 236    * by calling <code>InitializeAudioDecoder</code> or
 237    * <code>InitializeVideoDecoder</code>.
 238    *
 239    * De-initialization completion is reported to the browser using the
 240    * <code>DecoderDeinitializeDone()</code> method on the
 241    * <code>PPB_ContentDecryptor_Private</code> interface.
 242    *
 243    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 244    * specifies the decoder to de-initialize.
 245    *
 246    * @param[in] request_id A request ID that allows the browser to associate a
 247    * request to de-initialize a decoder with the corresponding call to the
 248    * <code>DecoderDeinitializeDone()</code> method on the
 249    * <code>PPB_ContentDecryptor_Private</code> interface.
 250    */
 251   void DeinitializeDecoder(
 252       [in] PP_Instance instance,
 253       [in] PP_DecryptorStreamType decoder_type,
 254       [in] uint32_t request_id);
 255
 256   /**
 257    * Resets the decoder for the <code>PP_DecryptorStreamType</code> specified
 258    * by <code>decoder_type</code> to an initialized clean state. Reset
 259    * completion is reported to the browser using the
 260    * <code>DecoderResetDone()</code> method on the
 261    * <code>PPB_ContentDecryptor_Private</code> interface. This method can be
 262    * used to signal a discontinuity in the encoded data stream, and is safe to
 263    * call multiple times.
 264    *
 265    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 266    * specifies the decoder to reset.
 267    *
 268    * @param[in] request_id A request ID that allows the browser to associate a
 269    * request to reset the decoder with a corresponding call to the
 270    * <code>DecoderResetDone()</code> method on the
 271    * <code>PPB_ContentDecryptor_Private</code> interface.
 272    */
 273   void ResetDecoder(
 274       [in] PP_Instance instance,
 275       [in] PP_DecryptorStreamType decoder_type,
 276       [in] uint32_t request_id);
 277
 278   /**
 279    * Decrypts encrypted_buffer, decodes it, and returns the unencrypted
 280    * uncompressed (decoded) data to the browser via the
 281    * <code>DeliverFrame()</code> or <code>DeliverSamples()</code> method on the
 282    * <code>PPB_ContentDecryptor_Private</code> interface.
 283    *
 284    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> that
 285    * specifies the decoder to use after <code>encrypted_buffer</code> is
 286    * decrypted.
 287    *
 288    * @param[in] encrypted_buffer A <code>PP_Resource</code> corresponding to a
 289    * <code>PPB_Buffer_Dev</code> resource that contains encrypted media data.
 290    *
 291    * @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
 292    * contains all auxiliary information needed for decryption of the
 293    * <code>encrypted_block</code>.
 294    */
 295   void DecryptAndDecode(
 296       [in] PP_Instance instance,
 297       [in] PP_DecryptorStreamType decoder_type,
 298       [in] PP_Resource encrypted_buffer,
 299       [in] PP_EncryptedBlockInfo encrypted_block_info);
 300 };