ppapi/c/private/ppb_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/ppb_content_decryptor_private.idl,
   7  *   modified Thu Mar 28 15:22:02 2013.
   8  */
   9
  10 #ifndef PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_
  11 #define PPAPI_C_PRIVATE_PPB_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 PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_6 \
  22     "PPB_ContentDecryptor_Private;0.6"
  23 #define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE \
  24     PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_6
  25
  26 /**
  27  * @file
  28  * This file defines the <code>PPB_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>PPB_ContentDecryptor_Private</code> structure contains the function
  40  * pointers the browser must implement to support plugins implementing the
  41  * <code>PPP_ContentDecryptor_Private</code> interface. This interface provides
  42  * browser side support for the Content Decryption Module (CDM) for v0.1 of the
  43  * proposed Encrypted Media Extensions: http://goo.gl/rbdnR
  44  */
  45 struct PPB_ContentDecryptor_Private_0_6 {
  46   /**
  47    * The decryptor requires a key that has not been provided.
  48    *
  49    * Sent when the decryptor encounters encrypted content, but it does not have
  50    * the key required to decrypt the data. The plugin will call this method in
  51    * response to a call to the <code>Decrypt()</code> method on the
  52    * <code>PPP_ContentDecryptor_Private<code> interface.
  53    *
  54    * The browser must notify the application that a key is needed, and, in
  55    * response, the web application must direct the browser to call
  56    * <code>AddKey()</code> on the <code>PPP_ContentDecryptor_Private</code>
  57    * interface.
  58    *
  59    * @param[in] key_system A <code>PP_Var</code> of type
  60    * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
  61    *
  62    * @param[in] session_id A <code>PP_Var</code> of type
  63    * <code>PP_VARTYPE_STRING</code> containing the session ID.
  64    *
  65    * @param[in] init_data A <code>PP_Var</code> of type
  66    * <code>PP_VARTYPE_ARRAY_BUFFER</code> containing container-specific
  67    * initialization data.
  68    */
  69   void (*NeedKey)(PP_Instance instance,
  70                   struct PP_Var key_system,
  71                   struct PP_Var session_id,
  72                   struct PP_Var init_data);
  73   /**
  74    * A key has been added as the result of a call to the <code>AddKey()</code>
  75    * method on the <code>PPP_ContentDecryptor_Private</code> interface.
  76    *
  77    * Note: The above describes the most simple case. Depending on the key
  78    * system, a series of <code>KeyMessage()</code> calls from the CDM will be
  79    * sent to the browser, and then on to the web application. The web
  80    * application must then provide more data to the CDM by directing the browser
  81    * to pass the data to the CDM via calls to <code>AddKey()</code> on the
  82    * <code>PPP_ContentDecryptor_Private</code> interface.
  83    * The CDM must call <code>KeyAdded()</code> when the sequence is completed,
  84    * and, in response, the browser must notify the web application.
  85    *
  86    * @param[in] key_system A <code>PP_Var</code> of type
  87    * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
  88    *
  89    * @param[in] session_id A <code>PP_Var</code> of type
  90    * <code>PP_VARTYPE_STRING</code> containing the session ID.
  91    */
  92   void (*KeyAdded)(PP_Instance instance,
  93                    struct PP_Var key_system,
  94                    struct PP_Var session_id);
  95   /**
  96    * A message or request has been generated for key_system in the CDM, and
  97    * must be sent to the web application.
  98    *
  99    * For example, when the browser invokes <code>GenerateKeyRequest()</code>
 100    * on the <code>PPP_ContentDecryptor_Private</code> interface, the plugin
 101    * must send a key message containing the key request.
 102    *
 103    * Note that <code>KeyMessage()</code> can be used for purposes other than
 104    * responses to <code>GenerateKeyRequest()</code> calls. See also the text
 105    * in the comment for <code>KeyAdded()</code>, which describes a sequence of
 106    * <code>AddKey()</code> and <code>KeyMessage()</code> calls required to
 107    * prepare for decryption.
 108    *
 109    * @param[in] key_system A <code>PP_Var</code> of type
 110    * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
 111    *
 112    * @param[in] session_id A <code>PP_Var</code> of type
 113    * <code>PP_VARTYPE_STRING</code> containing the session ID.
 114    *
 115    * @param[in] message A <code>PP_Var</code> of type
 116    * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the message.
 117    *
 118    * @param[in] default_url A <code>PP_Var</code> of type
 119    * <code>PP_VARTYPE_STRING</code> containing the default URL for the message.
 120    */
 121   void (*KeyMessage)(PP_Instance instance,
 122                      struct PP_Var key_system,
 123                      struct PP_Var session_id,
 124                      struct PP_Var message,
 125                      struct PP_Var default_url);
 126   /**
 127    * An error occurred in a <code>PPP_ContentDecryptor_Private</code> method,
 128    * or within the plugin implementing the interface.
 129    *
 130    * @param[in] key_system A <code>PP_Var</code> of type
 131    * <code>PP_VARTYPE_STRING</code> containing the name of the key system.
 132    *
 133    * @param[in] session_id A <code>PP_Var</code> of type
 134    * <code>PP_VARTYPE_STRING</code> containing the session ID.
 135    *
 136    * @param[in] media_error A MediaKeyError.
 137    *
 138    * @param[in] system_error A system error code.
 139    */
 140   void (*KeyError)(PP_Instance instance,
 141                    struct PP_Var key_system,
 142                    struct PP_Var session_id,
 143                    int32_t media_error,
 144                    int32_t system_code);
 145   /**
 146    * Called after the <code>Decrypt()</code> method on the
 147    * <code>PPP_ContentDecryptor_Private</code> interface completes to
 148    * deliver decrypted_block to the browser for decoding and rendering.
 149    *
 150    * The plugin must not hold a reference to the encrypted buffer resource
 151    * provided to <code>Decrypt()</code> when it calls this method. The browser
 152    * will reuse the buffer in a subsequent <code>Decrypt()</code> call.
 153    *
 154    * @param[in] decrypted_block A <code>PP_Resource</code> corresponding to a
 155    * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
 156    * block.
 157    *
 158    * @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
 159    * contains the result code and tracking info associated with the
 160    * <code>decrypted_block</code>.
 161    */
 162   void (*DeliverBlock)(
 163       PP_Instance instance,
 164       PP_Resource decrypted_block,
 165       const struct PP_DecryptedBlockInfo* decrypted_block_info);
 166   /**
 167    * Called after the <code>InitializeAudioDecoder()</code> or
 168    * <code>InitializeVideoDecoder()</code> method on the
 169    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 170    * decoder initialization status to the browser.
 171    *
 172    * @param[in] success A <code>PP_Bool</code> that is set to
 173    * <code>PP_TRUE</code> when the decoder initialization request associated
 174    * with <code>request_id</code> was successful.
 175    *
 176    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> identifying
 177    * the decoder type for which this initialization status response was sent.
 178    *
 179    * @param[in] request_id The <code>request_id</code> value passed to
 180    * <code>InitializeAudioDecoder</code> or <code>InitializeVideoDecoder</code>
 181    * in <code>PP_AudioDecoderConfig</code> or
 182    * <code>PP_VideoDecoderConfig</code>.
 183    */
 184   void (*DecoderInitializeDone)(PP_Instance instance,
 185                                 PP_DecryptorStreamType decoder_type,
 186                                 uint32_t request_id,
 187                                 PP_Bool success);
 188   /**
 189    * Called after the <code>DeinitializeDecoder()</code> method on the
 190    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 191    * decoder de-initialization completion to the browser.
 192    *
 193    * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
 194    * <code>DeinitializeDecoder()</code>.
 195    *
 196    * @param[in] request_id The <code>request_id</code> value passed to
 197    * <code>DeinitializeDecoder()</code>.
 198    */
 199   void (*DecoderDeinitializeDone)(PP_Instance instance,
 200                                   PP_DecryptorStreamType decoder_type,
 201                                   uint32_t request_id);
 202   /**
 203    * Called after the <code>ResetDecoder()</code> method on the
 204    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 205    * decoder reset completion to the browser.
 206    *
 207    * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
 208    * <code>ResetDecoder()</code>.
 209    *
 210    * @param[in] request_id The <code>request_id</code> value passed to
 211    * <code>ResetDecoder()</code>.
 212    */
 213   void (*DecoderResetDone)(PP_Instance instance,
 214                            PP_DecryptorStreamType decoder_type,
 215                            uint32_t request_id);
 216   /**
 217    * Called after the <code>DecryptAndDecode()</code> method on the
 218    * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
 219    * a decrypted and decoded video frame to the browser for rendering.
 220    *
 221    * The plugin must not hold a reference to the encrypted buffer resource
 222    * provided to <code>DecryptAndDecode()</code> when it calls this method. The
 223    * browser will reuse the buffer in a subsequent
 224    * <code>DecryptAndDecode()</code> call.
 225    *
 226    * @param[in] decrypted_frame A <code>PP_Resource</code> corresponding to a
 227    * <code>PPB_Buffer_Dev</code> resource that contains a video frame.
 228    *
 229    * @param[in] decrypted_frame_info A <code>PP_DecryptedFrameInfo</code> that
 230    * contains the result code, tracking info, and buffer format associated with
 231    * <code>decrypted_frame</code>.
 232    */
 233   void (*DeliverFrame)(
 234       PP_Instance instance,
 235       PP_Resource decrypted_frame,
 236       const struct PP_DecryptedFrameInfo* decrypted_frame_info);
 237   /**
 238    * Called after the <code>DecryptAndDecode()</code> method on the
 239    * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
 240    * a buffer of decrypted and decoded audio samples to the browser for
 241    * rendering.
 242    *
 243    * The plugin must not hold a reference to the encrypted buffer resource
 244    * provided to <code>DecryptAndDecode()</code> when it calls this method. The
 245    * browser will reuse the buffer in a subsequent
 246    * <code>DecryptAndDecode()</code> call.
 247    *
 248    * <code>audio_frames</code> can contain multiple audio output buffers. Each
 249    * buffer is serialized in this format:
 250    *
 251    * |<------------------- serialized audio buffer ------------------->|
 252    * | int64_t timestamp | int64_t length | length bytes of audio data |
 253    *
 254    * For example, with three audio output buffers, |audio_frames| will look
 255    * like this:
 256    *
 257    * |<---------------- audio_frames ------------------>|
 258    * | audio buffer 0 | audio buffer 1 | audio buffer 2 |
 259    *
 260    * @param[in] audio_frames A <code>PP_Resource</code> corresponding to a
 261    * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
 262    * of decoded audio samples.
 263    *
 264    * @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
 265    * contains the tracking info and result code associated with the
 266    * <code>decrypted_block</code>.
 267    */
 268   void (*DeliverSamples)(
 269       PP_Instance instance,
 270       PP_Resource audio_frames,
 271       const struct PP_DecryptedBlockInfo* decrypted_block_info);
 272 };
 273
 274 typedef struct PPB_ContentDecryptor_Private_0_6 PPB_ContentDecryptor_Private;
 275 /**
 276  * @}
 277  */
 278
 279 #endif  /* PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_ */
 280