ppapi/api/private/pp_content_decryptor.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  * The <code>PP_DecryptTrackingInfo</code> struct contains necessary information
   8  * that can be used to associate the decrypted block with a decrypt request
   9  * and/or an input block.
  10  */
  11 [assert_size(16)]
  12 struct PP_DecryptTrackingInfo {
  13   /**
  14    * Client-specified identifier for the associated decrypt request. By using
  15    * this value, the client can associate the decrypted block with a decryption
  16    * request.
  17    */
  18   uint32_t request_id;
  19
  20   /**
  21    * A unique buffer ID to identify a PPB_Buffer_Dev. Unlike a PP_Resource,
  22    * this ID is identical at both the renderer side and the plugin side.
  23    * In <code>PPB_ContentDecryptor_Private</code> calls, this is the ID of the
  24    * buffer associated with the decrypted block/frame/samples.
  25    * In <code>PPP_ContentDecryptor_Private</code> calls, this is the ID of a
  26    * buffer that is no longer need at the renderer side, which can be released
  27    * or recycled by the plugin. This ID can be 0 if there is no buffer to be
  28    * released or recycled.
  29    */
  30   uint32_t buffer_id;
  31
  32   /**
  33    * Timestamp in microseconds of the associated block. By using this value,
  34    * the client can associate the decrypted (and decoded) data with an input
  35    * block. This is needed because buffers may be delivered out of order and
  36    * not in response to the <code>request_id</code> they were provided with.
  37    */
  38   int64_t timestamp;
  39 };
  40
  41 /**
  42  * The <code>PP_DecryptSubsampleDescription</code> struct contains information
  43  * to support subsample decryption.
  44  *
  45  * An input block can be split into several continuous subsamples.
  46  * A <code>PP_DecryptSubsampleEntry</code> specifies the number of clear and
  47  * cipher bytes in each subsample. For example, the following block has three
  48  * subsamples:
  49  *
  50  * |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
  51  * |   clear1   |  cipher1  |  clear2  |   cipher2   | clear3 |    cipher3    |
  52  *
  53  * For decryption, all of the cipher bytes in a block should be treated as a
  54  * contiguous (in the subsample order) logical stream. The clear bytes should
  55  * not be considered as part of decryption.
  56  *
  57  * Logical stream to decrypt:   |  cipher1  |   cipher2   |    cipher3    |
  58  * Decrypted stream:            | decrypted1|  decrypted2 |   decrypted3  |
  59  *
  60  * After decryption, the decrypted bytes should be copied over the position
  61  * of the corresponding cipher bytes in the original block to form the output
  62  * block. Following the above example, the decrypted block should be:
  63  *
  64  * |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
  65  * |   clear1   | decrypted1|  clear2  |  decrypted2 | clear3 |   decrypted3  |
  66  */
  67 [assert_size(8)]
  68 struct PP_DecryptSubsampleDescription {
  69   /**
  70    * Size in bytes of clear data in a subsample entry.
  71    */
  72   uint32_t clear_bytes;
  73
  74   /**
  75    * Size in bytes of encrypted data in a subsample entry.
  76    */
  77   uint32_t cipher_bytes;
  78 };
  79
  80 /**
  81  * The <code>PP_EncryptedBlockInfo</code> struct contains all the information
  82  * needed to decrypt an encrypted block.
  83  */
  84 [assert_size(240)]
  85 struct PP_EncryptedBlockInfo {
  86   /**
  87    * Information needed by the client to track the block to be decrypted.
  88    */
  89   PP_DecryptTrackingInfo tracking_info;
  90
  91   /**
  92    * Size in bytes of data to be decrypted (data_offset included).
  93    */
  94   uint32_t data_size;
  95
  96   /**
  97    * Key ID of the block to be decrypted.
  98    *
  99    * TODO(xhwang): For WebM the key ID can be as large as 2048 bytes in theory.
 100    * But it's not used in current implementations. If we really need to support
 101    * it, we should move key ID out as a separate parameter, e.g.
 102    * as a <code>PP_Var</code>, or make the whole
 103    * <code>PP_EncryptedBlockInfo</code> as a <code>PP_Resource</code>.
 104    */
 105   uint8_t[64] key_id;
 106   uint32_t key_id_size;
 107
 108   /**
 109    * Initialization vector of the block to be decrypted.
 110    */
 111   uint8_t[16] iv;
 112   uint32_t iv_size;
 113
 114   /**
 115    * Subsample information of the block to be decrypted.
 116    */
 117   PP_DecryptSubsampleDescription[16] subsamples;
 118   uint32_t num_subsamples;
 119 };
 120
 121 /**
 122  * <code>PP_DecryptedFrameFormat</code> contains video frame formats.
 123  */
 124 [assert_size(4)]
 125 enum PP_DecryptedFrameFormat {
 126   PP_DECRYPTEDFRAMEFORMAT_UNKNOWN = 0,
 127   PP_DECRYPTEDFRAMEFORMAT_YV12 = 1,
 128   PP_DECRYPTEDFRAMEFORMAT_I420 = 2
 129 };
 130
 131 /**
 132  * <code>PP_DecryptedSampleFormat</code> contains audio sample formats.
 133  */
 134 [assert_size(4)]
 135 enum PP_DecryptedSampleFormat {
 136   PP_DECRYPTEDSAMPLEFORMAT_UNKNOWN = 0,
 137   PP_DECRYPTEDSAMPLEFORMAT_U8 = 1,
 138   PP_DECRYPTEDSAMPLEFORMAT_S16 = 2,
 139   PP_DECRYPTEDSAMPLEFORMAT_S32 = 3,
 140   PP_DECRYPTEDSAMPLEFORMAT_F32 = 4,
 141   PP_DECRYPTEDSAMPLEFORMAT_PLANAR_S16 = 5,
 142   PP_DECRYPTEDSAMPLEFORMAT_PLANAR_F32 = 6
 143 };
 144
 145 /**
 146  * The <code>PP_DecryptResult</code> enum contains decryption and decoding
 147  * result constants.
 148  */
 149 [assert_size(4)]
 150 enum PP_DecryptResult {
 151   /** The decryption (and/or decoding) operation finished successfully. */
 152   PP_DECRYPTRESULT_SUCCESS = 0,
 153   /** The decryptor did not have the necessary decryption key. */
 154   PP_DECRYPTRESULT_DECRYPT_NOKEY = 1,
 155   /** The input was accepted by the decoder but no frame(s) can be produced. */
 156   PP_DECRYPTRESULT_NEEDMOREDATA = 2,
 157   /** An unexpected error happened during decryption. */
 158   PP_DECRYPTRESULT_DECRYPT_ERROR = 3,
 159   /** An unexpected error happened during decoding. */
 160   PP_DECRYPTRESULT_DECODE_ERROR = 4
 161 };
 162
 163 /**
 164  * <code>PP_DecryptedBlockInfo</code> struct contains the decryption result and
 165  * tracking info associated with the decrypted block.
 166  */
 167 [assert_size(24)]
 168 struct PP_DecryptedBlockInfo {
 169   /**
 170    * Result of the decryption (and/or decoding) operation.
 171    */
 172   PP_DecryptResult result;
 173
 174   /**
 175    * Size in bytes of decrypted data, which may be less than the size of the
 176    * corresponding buffer.
 177    */
 178   uint32_t data_size;
 179
 180   /**
 181    * Information needed by the client to track the block to be decrypted.
 182    */
 183   PP_DecryptTrackingInfo tracking_info;
 184 };
 185
 186 /**
 187  * <code>PP_DecryptedFramePlanes</code> provides YUV plane index values for
 188  * accessing plane offsets stored in <code>PP_DecryptedFrameInfo</code>.
 189  */
 190 [assert_size(4)]
 191 enum PP_DecryptedFramePlanes {
 192   PP_DECRYPTEDFRAMEPLANES_Y = 0,
 193   PP_DECRYPTEDFRAMEPLANES_U = 1,
 194   PP_DECRYPTEDFRAMEPLANES_V = 2
 195 };
 196
 197 /**
 198  * <code>PP_DecryptedFrameInfo</code> contains the result of the
 199  * decrypt and decode operation on the associated frame, information required
 200  * to access the frame data in buffer, and tracking info.
 201  */
 202 [assert_size(56)]
 203 struct PP_DecryptedFrameInfo {
 204   /**
 205    * Result of the decrypt and decode operation.
 206    */
 207   PP_DecryptResult result;
 208
 209   /**
 210    * Format of the decrypted frame.
 211    */
 212   PP_DecryptedFrameFormat format;
 213
 214   /**
 215    * Offsets into the buffer resource for accessing video planes.
 216    */
 217   int32_t[3] plane_offsets;
 218
 219   /**
 220    * Stride of each plane.
 221    */
 222   int32_t[3] strides;
 223
 224   /**
 225    * Width of the video frame, in pixels.
 226    */
 227   int32_t width;
 228
 229   /**
 230    * Height of the video frame, in pixels.
 231    */
 232   int32_t height;
 233
 234   /**
 235    * Information needed by the client to track the decrypted frame.
 236    */
 237   PP_DecryptTrackingInfo tracking_info;
 238 };
 239
 240 /**
 241  * <code>PP_DecryptedSampleInfo</code> contains the result of the
 242  * decrypt and decode operation on the associated samples, information required
 243  * to access the sample data in buffer, and tracking info.
 244  */
 245 [assert_size(32)]
 246 struct PP_DecryptedSampleInfo {
 247   /**
 248    * Result of the decrypt and decode operation.
 249    */
 250   PP_DecryptResult result;
 251
 252   /**
 253    * Format of the decrypted samples.
 254    */
 255   PP_DecryptedSampleFormat format;
 256
 257   /**
 258    * Size in bytes of decrypted samples.
 259    */
 260   uint32_t data_size;
 261
 262   /**
 263    * 4-byte padding to make the size of <code>PP_DecryptedSampleInfo</code>
 264    * a multiple of 8 bytes. The value of this field should not be used.
 265    */
 266   uint32_t padding;
 267
 268   /**
 269    * Information needed by the client to track the decrypted samples.
 270    */
 271   PP_DecryptTrackingInfo tracking_info;
 272 };
 273
 274 /**
 275  * <code>PP_AudioCodec</code> contains audio codec type constants.
 276  */
 277 [assert_size(4)]
 278 enum PP_AudioCodec {
 279   PP_AUDIOCODEC_UNKNOWN = 0,
 280   PP_AUDIOCODEC_VORBIS = 1,
 281   PP_AUDIOCODEC_AAC = 2
 282 };
 283
 284 /**
 285  * <code>PP_AudioDecoderConfig</code> contains audio decoder configuration
 286  * information required to initialize audio decoders, and a request ID
 287  * that allows clients to associate a decoder initialization request with a
 288  * status response. Note: When <code>codec</code> requires extra data for
 289  * initialization, the data is sent as a <code>PP_Resource</code> carried
 290  * alongside <code>PP_AudioDecoderConfig</code>.
 291  */
 292  [assert_size(20)]
 293 struct PP_AudioDecoderConfig {
 294   /**
 295    * The audio codec to initialize.
 296    */
 297   PP_AudioCodec codec;
 298
 299   /**
 300    * Number of audio channels.
 301    */
 302   int32_t channel_count;
 303
 304   /**
 305    * Size of each audio channel.
 306    */
 307   int32_t bits_per_channel;
 308
 309   /**
 310    * Audio sampling rate.
 311    */
 312   int32_t samples_per_second;
 313
 314   /**
 315    * Client-specified identifier for the associated audio decoder initialization
 316    * request. By using this value, the client can associate a decoder
 317    * initialization status response with an initialization request.
 318    */
 319   uint32_t request_id;
 320 };
 321
 322 /**
 323  * <code>PP_VideoCodec</code> contains video codec type constants.
 324  */
 325 [assert_size(4)]
 326 enum PP_VideoCodec {
 327   PP_VIDEOCODEC_UNKNOWN = 0,
 328   PP_VIDEOCODEC_VP8 = 1,
 329   PP_VIDEOCODEC_H264 = 2,
 330   PP_VIDEOCODEC_VP9 = 3
 331 };
 332
 333 /**
 334  * <code>PP_VideoCodecProfile</code> contains video codec profile type
 335  * constants required for video decoder configuration.
 336  *.
 337  */
 338 [assert_size(4)]
 339 enum PP_VideoCodecProfile {
 340   PP_VIDEOCODECPROFILE_UNKNOWN = 0,
 341   PP_VIDEOCODECPROFILE_NOT_NEEDED = 1,
 342   PP_VIDEOCODECPROFILE_H264_BASELINE = 2,
 343   PP_VIDEOCODECPROFILE_H264_MAIN = 3,
 344   PP_VIDEOCODECPROFILE_H264_EXTENDED = 4,
 345   PP_VIDEOCODECPROFILE_H264_HIGH = 5,
 346   PP_VIDEOCODECPROFILE_H264_HIGH_10 = 6,
 347   PP_VIDEOCODECPROFILE_H264_HIGH_422 = 7,
 348   PP_VIDEOCODECPROFILE_H264_HIGH_444_PREDICTIVE = 8
 349 };
 350
 351 /**
 352  * <code>PP_VideoDecoderConfig</code> contains video decoder configuration
 353  * information required to initialize video decoders, and a request ID
 354  * that allows clients to associate a decoder initialization request with a
 355  * status response. Note: When <code>codec</code> requires extra data for
 356  * initialization, the data is sent as a <code>PP_Resource</code> carried
 357  * alongside <code>PP_VideoDecoderConfig</code>.
 358  */
 359 [assert_size(24)]
 360 struct PP_VideoDecoderConfig {
 361   /**
 362    * The video codec to initialize.
 363    */
 364   PP_VideoCodec codec;
 365
 366   /**
 367    * Profile to use when initializing the video codec.
 368    */
 369   PP_VideoCodecProfile profile;
 370
 371   /**
 372    * Output video format.
 373    */
 374   PP_DecryptedFrameFormat format;
 375
 376   /**
 377    * Width of decoded video frames, in pixels.
 378    */
 379   int32_t width;
 380
 381   /**
 382    * Height of decoded video frames, in pixels.
 383    */
 384   int32_t height;
 385
 386   /**
 387    * Client-specified identifier for the associated video decoder initialization
 388    * request. By using this value, the client can associate a decoder
 389    * initialization status response with an initialization request.
 390    */
 391   uint32_t request_id;
 392 };
 393
 394 /**
 395  * <code>PP_DecryptorStreamType</code> contains stream type constants.
 396  */
 397 [assert_size(4)]
 398 enum PP_DecryptorStreamType {
 399   PP_DECRYPTORSTREAMTYPE_AUDIO = 0,
 400   PP_DECRYPTORSTREAMTYPE_VIDEO = 1
 401 };
 402
 403 /**
 404  * <code>PP_SessionType</code> contains session type constants.
 405  */
 406 [assert_size(4)]
 407 enum PP_SessionType {
 408   PP_SESSIONTYPE_TEMPORARY = 0,
 409   PP_SESSIONTYPE_PERSISTENT_LICENSE = 1,
 410   PP_SESSIONTYPE_PERSISTENT_RELEASE = 2
 411 };
 412
 413 /**
 414  * <code>PP_InitDataType</code> contains Initialization Data Type constants.
 415  */
 416 [assert_size(4)]
 417 enum PP_InitDataType {
 418   PP_INITDATATYPE_CENC = 0,
 419   PP_INITDATATYPE_KEYIDS = 1,
 420   PP_INITDATATYPE_WEBM = 2
 421 };
 422
 423 /**
 424  * <code>PP_CdmExceptionCode</code> contains exception code constants.
 425  */
 426 [assert_size(4)]
 427 enum PP_CdmExceptionCode {
 428   PP_CDMEXCEPTIONCODE_NOTSUPPORTEDERROR = 1,
 429   PP_CDMEXCEPTIONCODE_INVALIDSTATEERROR = 2,
 430   PP_CDMEXCEPTIONCODE_INVALIDACCESSERROR = 3,
 431   PP_CDMEXCEPTIONCODE_QUOTAEXCEEDEDERROR = 4,
 432   PP_CDMEXCEPTIONCODE_UNKNOWNERROR = 5,
 433   PP_CDMEXCEPTIONCODE_CLIENTERROR = 6,
 434   PP_CDMEXCEPTIONCODE_OUTPUTERROR = 7
 435 };
 436
 437 /**
 438  * <code>PP_CdmMessageType</code> contains message type constants.
 439  */
 440 [assert_size(4)]
 441 enum PP_CdmMessageType {
 442   PP_CDMMESSAGETYPE_LICENSE_REQUEST = 0,
 443   PP_CDMMESSAGETYPE_LICENSE_RENEWAL = 1,
 444   PP_CDMMESSAGETYPE_LICENSE_RELEASE = 2
 445 };
 446
 447 /**
 448  * <code>PP_CdmKeyStatus</code> contains key status constants.
 449  */
 450 [assert_size(4)]
 451 enum PP_CdmKeyStatus {
 452   PP_CDMKEYSTATUS_USABLE = 0,
 453   PP_CDMKEYSTATUS_INVALID = 1,
 454   PP_CDMKEYSTATUS_EXPIRED = 2,
 455   PP_CDMKEYSTATUS_OUTPUTRESTRICTED = 3,
 456   PP_CDMKEYSTATUS_OUTPUTDOWNSCALED = 4,
 457   PP_CDMKEYSTATUS_STATUSPENDING = 5
 458 };
 459
 460 /**
 461  * The <code>PP_KeyInformation</code> struct contains information about a
 462  * key used for decryption.
 463  */
 464 [assert_size(524)]
 465 struct PP_KeyInformation {
 466   /**
 467    * Key ID.
 468    */
 469   uint8_t[512] key_id;
 470   uint32_t key_id_size;
 471
 472   /**
 473    * Status of this key.
 474    */
 475   PP_CdmKeyStatus key_status;
 476
 477   /**
 478    * Optional error code for keys that are not usable.
 479    */
 480   uint32_t system_code;
 481 };