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