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