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