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