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