src/ppapi/c/private/ppp_content_decryptor_private.h

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