ppapi/api/private/ppb_content_decryptor_private.idl

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