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