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 Jun  5 13:39:15 2014.
   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_12 \
  22     "PPB_ContentDecryptor_Private;0.12"
  23 #define PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE \
  24     PPB_CONTENTDECRYPTOR_PRIVATE_INTERFACE_0_12
  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 Encrypted
  43  * Media Extensions: http://www.w3.org/TR/encrypted-media/
  44  */
  45 struct PPB_ContentDecryptor_Private_0_12 {
  46   /**
  47    * A promise has been resolved by the CDM.
  48    *
  49    * @param[in] promise_id Identifies the promise that the CDM resolved.
  50    */
  51   void (*PromiseResolved)(PP_Instance instance, uint32_t promise_id);
  52   /**
  53    * A promise has been resolved by the CDM.
  54    *
  55    * @param[in] promise_id Identifies the promise that the CDM resolved.
  56    *
  57    * @param[in] web_session_id A <code>PP_Var</code> of type
  58    * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute.
  59    */
  60   void (*PromiseResolvedWithSession)(PP_Instance instance,
  61                                      uint32_t promise_id,
  62                                      struct PP_Var web_session_id);
  63   /**
  64    * A promise has been rejected by the CDM due to an error.
  65    *
  66    * @param[in] promise_id Identifies the promise that the CDM rejected.
  67    *
  68    * @param[in] exception_code A <code>PP_CdmExceptionCode</code> containing
  69    * the exception code.
  70    *
  71    * @param[in] system_code A system error code.
  72    *
  73    * @param[in] error_description A <code>PP_Var</code> of type
  74    * <code>PP_VARTYPE_STRING</code> containing the error description.
  75    */
  76   void (*PromiseRejected)(PP_Instance instance,
  77                           uint32_t promise_id,
  78                           PP_CdmExceptionCode exception_code,
  79                           uint32_t system_code,
  80                           struct PP_Var error_description);
  81   /**
  82    * A message or request has been generated for key_system in the CDM, and
  83    * must be sent to the web application.
  84    *
  85    * For example, when the browser invokes <code>CreateSession()</code>
  86    * on the <code>PPP_ContentDecryptor_Private</code> interface, the plugin
  87    * must send a message containing the license request.
  88    *
  89    * Note that <code>SessionMessage()</code> can be used for purposes other than
  90    * responses to <code>CreateSession()</code> calls. See also the text
  91    * in the comment for <code>SessionReady()</code>, which describes a sequence
  92    * of <code>UpdateSession()</code> and <code>SessionMessage()</code> calls
  93    * required to prepare for decryption.
  94    *
  95    * @param[in] web_session_id A <code>PP_Var</code> of type
  96    * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute for
  97    * which the message is intended.
  98    *
  99    * @param[in] message A <code>PP_Var</code> of type
 100    * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the message.
 101    *
 102    * @param[in] destination_url A <code>PP_Var</code> of type
 103    * <code>PP_VARTYPE_STRING</code> containing the destination URL for the
 104    * message.
 105    */
 106   void (*SessionMessage)(PP_Instance instance,
 107                          struct PP_Var web_session_id,
 108                          struct PP_Var message,
 109                          struct PP_Var destination_url);
 110   /**
 111    * The session is now ready to decrypt the media stream.
 112    *
 113    * Note: The above describes the most simple case. Depending on the key
 114    * system, a series of <code>SessionMessage()</code> calls from the CDM will
 115    * be sent to the browser, and then on to the web application. The web
 116    * application must then provide more data to the CDM by directing the browser
 117    * to pass the data to the CDM via calls to <code>UpdateSession()</code> on
 118    * the <code>PPP_ContentDecryptor_Private</code> interface.
 119    * The CDM must call <code>SessionReady()</code> when the sequence is
 120    * completed, and, in response, the browser must notify the web application.
 121    *
 122    * @param[in] web_session_id A <code>PP_Var</code> of type
 123    * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
 124    * the session that is now ready.
 125    */
 126   void (*SessionReady)(PP_Instance instance, struct PP_Var web_session_id);
 127   /**
 128    * The session has been closed as the result of a call to the
 129    * <code>ReleaseSession()</code> method on the
 130    * <code>PPP_ContentDecryptor_Private</code> interface, or due to other
 131    * factors as determined by the CDM.
 132    *
 133    * @param[in] web_session_id A <code>PP_Var</code> of type
 134    * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
 135    * the session that is now closed.
 136    */
 137   void (*SessionClosed)(PP_Instance instance, struct PP_Var web_session_id);
 138   /**
 139    * An error occurred in a <code>PPP_ContentDecryptor_Private</code> method,
 140    * or within the plugin implementing the interface.
 141    *
 142    * @param[in] web_session_id A <code>PP_Var</code> of type
 143    * <code>PP_VARTYPE_STRING</code> containing the session's ID attribute of
 144    * the session that caused the error.
 145    *
 146    * @param[in] exception_code A <code>PP_CdmExceptionCode</code> containing
 147    * the exception code.
 148    *
 149    * @param[in] system_code A system error code.
 150    *
 151    * @param[in] error_description A <code>PP_Var</code> of type
 152    * <code>PP_VARTYPE_STRING</code> containing the error description.
 153    */
 154   void (*SessionError)(PP_Instance instance,
 155                        struct PP_Var web_session_id,
 156                        PP_CdmExceptionCode exception_code,
 157                        uint32_t system_code,
 158                        struct PP_Var error_description);
 159   /**
 160    * Called after the <code>Decrypt()</code> method on the
 161    * <code>PPP_ContentDecryptor_Private</code> interface completes to
 162    * deliver decrypted_block to the browser for decoding and rendering.
 163    *
 164    * The plugin must not hold a reference to the encrypted buffer resource
 165    * provided to <code>Decrypt()</code> when it calls this method. The browser
 166    * will reuse the buffer in a subsequent <code>Decrypt()</code> call.
 167    *
 168    * @param[in] decrypted_block A <code>PP_Resource</code> corresponding to a
 169    * <code>PPB_Buffer_Dev</code> resource that contains a decrypted data
 170    * block.
 171    *
 172    * @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
 173    * contains the result code and tracking info associated with the
 174    * <code>decrypted_block</code>.
 175    */
 176   void (*DeliverBlock)(
 177       PP_Instance instance,
 178       PP_Resource decrypted_block,
 179       const struct PP_DecryptedBlockInfo* decrypted_block_info);
 180   /**
 181    * Called after the <code>InitializeAudioDecoder()</code> or
 182    * <code>InitializeVideoDecoder()</code> method on the
 183    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 184    * decoder initialization status to the browser.
 185    *
 186    * @param[in] success A <code>PP_Bool</code> that is set to
 187    * <code>PP_TRUE</code> when the decoder initialization request associated
 188    * with <code>request_id</code> was successful.
 189    *
 190    * @param[in] decoder_type A <code>PP_DecryptorStreamType</code> identifying
 191    * the decoder type for which this initialization status response was sent.
 192    *
 193    * @param[in] request_id The <code>request_id</code> value passed to
 194    * <code>InitializeAudioDecoder</code> or <code>InitializeVideoDecoder</code>
 195    * in <code>PP_AudioDecoderConfig</code> or
 196    * <code>PP_VideoDecoderConfig</code>.
 197    */
 198   void (*DecoderInitializeDone)(PP_Instance instance,
 199                                 PP_DecryptorStreamType decoder_type,
 200                                 uint32_t request_id,
 201                                 PP_Bool success);
 202   /**
 203    * Called after the <code>DeinitializeDecoder()</code> method on the
 204    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 205    * decoder de-initialization completion to the browser.
 206    *
 207    * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
 208    * <code>DeinitializeDecoder()</code>.
 209    *
 210    * @param[in] request_id The <code>request_id</code> value passed to
 211    * <code>DeinitializeDecoder()</code>.
 212    */
 213   void (*DecoderDeinitializeDone)(PP_Instance instance,
 214                                   PP_DecryptorStreamType decoder_type,
 215                                   uint32_t request_id);
 216   /**
 217    * Called after the <code>ResetDecoder()</code> method on the
 218    * <code>PPP_ContentDecryptor_Private</code> interface completes to report
 219    * decoder reset completion to the browser.
 220    *
 221    * @param[in] decoder_type The <code>PP_DecryptorStreamType</code> passed to
 222    * <code>ResetDecoder()</code>.
 223    *
 224    * @param[in] request_id The <code>request_id</code> value passed to
 225    * <code>ResetDecoder()</code>.
 226    */
 227   void (*DecoderResetDone)(PP_Instance instance,
 228                            PP_DecryptorStreamType decoder_type,
 229                            uint32_t request_id);
 230   /**
 231    * Called after the <code>DecryptAndDecode()</code> method on the
 232    * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
 233    * a decrypted and decoded video frame to the browser for rendering.
 234    *
 235    * The plugin must not hold a reference to the encrypted buffer resource
 236    * provided to <code>DecryptAndDecode()</code> when it calls this method. The
 237    * browser will reuse the buffer in a subsequent
 238    * <code>DecryptAndDecode()</code> call.
 239    *
 240    * @param[in] decrypted_frame A <code>PP_Resource</code> corresponding to a
 241    * <code>PPB_Buffer_Dev</code> resource that contains a video frame.
 242    *
 243    * @param[in] decrypted_frame_info A <code>PP_DecryptedFrameInfo</code> that
 244    * contains the result code, tracking info, and buffer format associated with
 245    * <code>decrypted_frame</code>.
 246    */
 247   void (*DeliverFrame)(
 248       PP_Instance instance,
 249       PP_Resource decrypted_frame,
 250       const struct PP_DecryptedFrameInfo* decrypted_frame_info);
 251   /**
 252    * Called after the <code>DecryptAndDecode()</code> method on the
 253    * <code>PPP_ContentDecryptor_Private</code> interface completes to deliver
 254    * a buffer of decrypted and decoded audio samples to the browser for
 255    * rendering.
 256    *
 257    * The plugin must not hold a reference to the encrypted buffer resource
 258    * provided to <code>DecryptAndDecode()</code> when it calls this method. The
 259    * browser will reuse the buffer in a subsequent
 260    * <code>DecryptAndDecode()</code> call.
 261    *
 262    * <code>audio_frames</code> can contain multiple audio output buffers. Each
 263    * buffer is serialized in this format:
 264    *
 265    * |<------------------- serialized audio buffer ------------------->|
 266    * | int64_t timestamp | int64_t length | length bytes of audio data |
 267    *
 268    * For example, with three audio output buffers, |audio_frames| will look
 269    * like this:
 270    *
 271    * |<---------------- audio_frames ------------------>|
 272    * | audio buffer 0 | audio buffer 1 | audio buffer 2 |
 273    *
 274    * @param[in] audio_frames A <code>PP_Resource</code> corresponding to a
 275    * <code>PPB_Buffer_Dev</code> resource that contains a decrypted buffer
 276    * of decoded audio samples.
 277    *
 278    * @param[in] decrypted_sample_info A <code>PP_DecryptedSampleInfo</code> that
 279    * contains the tracking info and result code associated with the decrypted
 280    * samples.
 281    */
 282   void (*DeliverSamples)(
 283       PP_Instance instance,
 284       PP_Resource audio_frames,
 285       const struct PP_DecryptedSampleInfo* decrypted_sample_info);
 286 };
 287
 288 typedef struct PPB_ContentDecryptor_Private_0_12 PPB_ContentDecryptor_Private;
 289 /**
 290  * @}
 291  */
 292
 293 #endif  /* PPAPI_C_PRIVATE_PPB_CONTENT_DECRYPTOR_PRIVATE_H_ */
 294