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.
5 #ifndef CDM_CONTENT_DECRYPTION_MODULE_H_
6 #define CDM_CONTENT_DECRYPTION_MODULE_H_
9 typedef unsigned char uint8_t;
10 typedef unsigned int uint32_t;
12 typedef __int64 int64_t;
17 // Define CDM_EXPORT so that functionality implemented by the CDM module
18 // can be exported to consumers.
21 #if defined(CDM_IMPLEMENTATION)
22 #define CDM_EXPORT __declspec(dllexport)
24 #define CDM_EXPORT __declspec(dllimport)
25 #endif // defined(CDM_IMPLEMENTATION)
27 #else // defined(WIN32)
29 #if defined(CDM_IMPLEMENTATION)
30 #define CDM_EXPORT __attribute__((visibility("default")))
35 #endif // defined(WIN32)
37 // The version number must be rolled when the exported functions are updated!
38 // If the CDM and the adapter use different versions of these functions, the
39 // adapter will fail to load or crash!
40 #define CDM_MODULE_VERSION 4
42 // Build the versioned entrypoint name.
43 // The extra macros are necessary to expand version to an actual value.
44 #define INITIALIZE_CDM_MODULE \
45 BUILD_ENTRYPOINT(InitializeCdmModule, CDM_MODULE_VERSION)
46 #define BUILD_ENTRYPOINT(name, version) \
47 BUILD_ENTRYPOINT_NO_EXPANSION(name, version)
48 #define BUILD_ENTRYPOINT_NO_EXPANSION(name, version) name##_##version
51 CDM_EXPORT void INITIALIZE_CDM_MODULE();
53 CDM_EXPORT void DeinitializeCdmModule();
55 // Returns a pointer to the requested CDM Host interface upon success.
56 // Returns NULL if the requested CDM Host interface is not supported.
57 // The caller should cast the returned pointer to the type matching
58 // |host_interface_version|.
59 typedef void* (*GetCdmHostFunc)(int host_interface_version, void* user_data);
61 // Returns a pointer to the requested CDM upon success.
62 // Returns NULL if an error occurs or the requested |cdm_interface_version| or
63 // |key_system| is not supported or another error occurs.
64 // The caller should cast the returned pointer to the type matching
65 // |cdm_interface_version|.
66 // Caller retains ownership of arguments and must call Destroy() on the returned
68 CDM_EXPORT void* CreateCdmInstance(
69 int cdm_interface_version,
70 const char* key_system, uint32_t key_system_size,
71 GetCdmHostFunc get_cdm_host_func, void* user_data);
73 CDM_EXPORT const char* GetCdmVersion();
87 kNeedMoreData, // Decoder needs more data to produce a decoded frame/sample.
88 kNoKey, // The required decryption key is not available.
89 kSessionError, // Session management error.
90 kDecryptError, // Decryption failed.
91 kDecodeError, // Error decoding audio or video.
92 kDeferredInitialization // Decoder is not ready for initialization.
95 // This must be consistent with MediaKeyError defined in the spec:
96 // https://dvcs.w3.org/hg/html-media/raw-file/eme-v0.1b/encrypted-media/encrypted-media.html#error-codes
97 // Support the minimum required set with backwards compatible values.
99 kPrefixedUnknownError = 1,
100 kPrefixedClientError = 2,
101 kPrefixedOutputError = 4
104 // This must at least contain the exceptions defined in the spec:
105 // https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#exceptions
106 // The following starts with the list of DOM4 exceptions from:
107 // http://www.w3.org/TR/dom/#domexception
108 // Some DOM4 exceptions are not included as they are not expected to be used.
110 kNotSupportedError = 9,
111 kInvalidStateError = 11,
112 kInvalidAccessError = 15,
113 kQuotaExceededError = 22,
115 // Additional exceptions that do not have assigned codes.
116 // There are other non-EME-specific values, not included in this list.
119 // Additional values from previous EME versions. They currently have no
120 // matching DOMException.
125 // Time is defined as the number of seconds since the
126 // Epoch (00:00:00 UTC, January 1, 1970).
129 // An input buffer can be split into several continuous subsamples.
130 // A SubsampleEntry specifies the number of clear and cipher bytes in each
131 // subsample. For example, the following buffer has three subsamples:
133 // |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
134 // | clear1 | cipher1 | clear2 | cipher2 | clear3 | cipher3 |
136 // For decryption, all of the cipher bytes in a buffer should be concatenated
137 // (in the subsample order) into a single logical stream. The clear bytes should
138 // not be considered as part of decryption.
140 // Stream to decrypt: | cipher1 | cipher2 | cipher3 |
141 // Decrypted stream: | decrypted1| decrypted2 | decrypted3 |
143 // After decryption, the decrypted bytes should be copied over the position
144 // of the corresponding cipher bytes in the original buffer to form the output
145 // buffer. Following the above example, the decrypted buffer should be:
147 // |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
148 // | clear1 | decrypted1| clear2 | decrypted2 | clear3 | decrypted3 |
150 // TODO(xhwang): Add checks to make sure these structs have fixed layout.
151 struct SubsampleEntry {
152 SubsampleEntry(uint32_t clear_bytes, uint32_t cipher_bytes)
153 : clear_bytes(clear_bytes), cipher_bytes(cipher_bytes) {}
155 uint32_t clear_bytes;
156 uint32_t cipher_bytes;
159 // Represents an input buffer to be decrypted (and possibly decoded). It does
160 // not own any pointers in this struct. If |iv_size| = 0, the data is
174 const uint8_t* data; // Pointer to the beginning of the input data.
175 uint32_t data_size; // Size (in bytes) of |data|.
177 const uint8_t* key_id; // Key ID to identify the decryption key.
178 uint32_t key_id_size; // Size (in bytes) of |key_id|.
180 const uint8_t* iv; // Initialization vector.
181 uint32_t iv_size; // Size (in bytes) of |iv|.
183 const struct SubsampleEntry* subsamples;
184 uint32_t num_subsamples; // Number of subsamples in |subsamples|.
186 int64_t timestamp; // Presentation timestamp in microseconds.
189 struct AudioDecoderConfig {
191 kUnknownAudioCodec = 0,
197 : codec(kUnknownAudioCodec),
200 samples_per_second(0),
202 extra_data_size(0) {}
205 int32_t channel_count;
206 int32_t bits_per_channel;
207 int32_t samples_per_second;
209 // Optional byte data required to initialize audio decoders, such as the
210 // vorbis setup header.
212 uint32_t extra_data_size;
215 // Supported sample formats for AudioFrames.
217 kUnknownAudioFormat = 0, // Unknown format value. Used for error reporting.
218 kAudioFormatU8, // Interleaved unsigned 8-bit w/ bias of 128.
219 kAudioFormatS16, // Interleaved signed 16-bit.
220 kAudioFormatS32, // Interleaved signed 32-bit.
221 kAudioFormatF32, // Interleaved float 32-bit.
222 kAudioFormatPlanarS16, // Signed 16-bit planar.
223 kAudioFormatPlanarF32, // Float 32-bit planar.
226 // Surface formats based on FOURCC labels, see: http://www.fourcc.org/yuv.php
228 kUnknownVideoFormat = 0, // Unknown format value. Used for error reporting.
229 kYv12, // 12bpp YVU planar 1x1 Y, 2x2 VU samples.
230 kI420 // 12bpp YVU planar 1x1 Y, 2x2 UV samples.
234 Size() : width(0), height(0) {}
235 Size(int32_t width, int32_t height) : width(width), height(height) {}
241 struct VideoDecoderConfig {
243 kUnknownVideoCodec = 0,
249 enum VideoCodecProfile {
250 kUnknownVideoCodecProfile = 0,
252 kH264ProfileBaseline,
254 kH264ProfileExtended,
258 kH264ProfileHigh444Predictive
262 : codec(kUnknownVideoCodec),
263 profile(kUnknownVideoCodecProfile),
264 format(kUnknownVideoFormat),
266 extra_data_size(0) {}
269 VideoCodecProfile profile;
272 // Width and height of video frame immediately post-decode. Not all pixels
273 // in this region are valid.
276 // Optional byte data required to initialize video decoders, such as H.264
279 uint32_t extra_data_size;
283 kStreamTypeAudio = 0,
287 // Structure provided to ContentDecryptionModule::OnPlatformChallengeResponse()
288 // after a platform challenge was initiated via Host::SendPlatformChallenge().
289 // All values will be NULL / zero in the event of a challenge failure.
290 struct PlatformChallengeResponse {
291 // |challenge| provided during Host::SendPlatformChallenge() combined with
292 // nonce data and signed with the platform's private key.
293 const uint8_t* signed_data;
294 uint32_t signed_data_length;
296 // RSASSA-PKCS1-v1_5-SHA256 signature of the |signed_data| block.
297 const uint8_t* signed_data_signature;
298 uint32_t signed_data_signature_length;
300 // X.509 device specific certificate for the |service_id| requested.
301 const uint8_t* platform_key_certificate;
302 uint32_t platform_key_certificate_length;
305 // Used when passing arrays of binary data. Does not own the referenced data.
307 BinaryData() : data(NULL), length(0) {}
312 // Supported output protection methods for use with EnableOutputProtection() and
313 // returned by OnQueryOutputProtectionStatus().
314 enum OutputProtectionMethods {
316 kProtectionHDCP = 1 << 0
319 // Connected output link types returned by OnQueryOutputProtectionStatus().
320 enum OutputLinkTypes {
322 kLinkTypeUnknown = 1 << 0,
323 kLinkTypeInternal = 1 << 1,
324 kLinkTypeVGA = 1 << 2,
325 kLinkTypeHDMI = 1 << 3,
326 kLinkTypeDVI = 1 << 4,
327 kLinkTypeDisplayPort = 1 << 5,
328 kLinkTypeNetwork = 1 << 6
331 // The type of session to create. The valid types are defined in the spec:
332 // https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#dom-sessiontype
338 // FileIO interface provides a way for the CDM to store data in a file in
339 // persistent storage. This interface aims only at providing basic read/write
340 // capabilities and should not be used as a full fledged file IO API.
341 // Each CDM and origin (e.g. HTTPS, "foo.example.com", 443) combination has
342 // its own persistent storage. All instances of a given CDM associated with a
343 // given origin share the same persistent storage.
344 // Note to implementors of this interface:
345 // Per-origin storage and the ability for users to clear it are important.
346 // See http://www.w3.org/TR/encrypted-media/#privacy-storedinfo.
349 // Opens the file with |file_name| for read and write.
350 // FileIOClient::OnOpenComplete() will be called after the opening
351 // operation finishes.
352 // - When the file is opened by a CDM instance, it will be classified as "in
353 // use". In this case other CDM instances in the same domain may receive
354 // kInUse status when trying to open it.
355 // - |file_name| must not contain forward slash ('/') or backslash ('\'), and
356 // must not start with an underscore ('_').
357 virtual void Open(const char* file_name, uint32_t file_name_size) = 0;
359 // Reads the contents of the file. FileIOClient::OnReadComplete() will be
360 // called with the read status. Read() should not be called if a previous
361 // Read() or Write() call is still pending; otherwise OnReadComplete() will
362 // be called with kInUse.
363 virtual void Read() = 0;
365 // Writes |data_size| bytes of |data| into the file.
366 // FileIOClient::OnWriteComplete() will be called with the write status.
367 // All existing contents in the file will be overwritten. Calling Write() with
368 // NULL |data| will clear all contents in the file. Write() should not be
369 // called if a previous Write() or Read() call is still pending; otherwise
370 // OnWriteComplete() will be called with kInUse.
371 virtual void Write(const uint8_t* data, uint32_t data_size) = 0;
373 // Closes the file if opened, destroys this FileIO object and releases any
374 // resources allocated. The CDM must call this method when it finished using
375 // this object. A FileIO object must not be used after Close() is called.
376 virtual void Close() = 0;
383 // Responses to FileIO calls. All responses will be called asynchronously.
384 // When kError is returned, the FileIO object could be in an error state. All
385 // following calls (other than Close()) could return kError. The CDM should
386 // still call Close() to destroy the FileIO object.
395 // Response to a FileIO::Open() call with the open |status|.
396 virtual void OnOpenComplete(Status status) = 0;
398 // Response to a FileIO::Read() call to provide |data_size| bytes of |data|
399 // read from the file.
400 // - kSuccess indicates that all contents of the file has been successfully
401 // read. In this case, 0 |data_size| means that the file is empty.
402 // - kInUse indicates that there are other read/write operations pending.
403 // - kError indicates read failure, e.g. the storage is not open or cannot be
405 virtual void OnReadComplete(Status status,
406 const uint8_t* data, uint32_t data_size) = 0;
408 // Response to a FileIO::Write() call.
409 // - kSuccess indicates that all the data has been written into the file
411 // - kInUse indicates that there are other read/write operations pending.
412 // - kError indicates write failure, e.g. the storage is not open or cannot be
413 // fully written. Upon write failure, the contents of the file should be
414 // regarded as corrupt and should not used.
415 virtual void OnWriteComplete(Status status) = 0;
419 virtual ~FileIOClient() {}
422 // ContentDecryptionModule interface that all CDMs need to implement.
423 // The interface is versioned for backward compatibility.
424 // Note: ContentDecryptionModule implementations must use the allocator
425 // provided in CreateCdmInstance() to allocate any Buffer that needs to
426 // be passed back to the caller. Implementations must call Buffer::Destroy()
427 // when a Buffer is created that will never be returned to the caller.
428 class ContentDecryptionModule_6 {
430 static const int kVersion = 6;
433 // CreateSession(), LoadSession(), UpdateSession(), and ReleaseSession()
434 // accept a |promise_id|, which must be passed to the completion Host method
435 // (e.g. Host::OnResolveNewSessionPromise()).
437 // Creates a session given |init_data_type|, |init_data| and |session_type|.
438 // The CDM must respond by calling either Host::OnResolveNewSessionPromise()
439 // or Host::OnRejectPromise().
440 virtual void CreateSession(
442 const char* init_data_type, uint32_t init_data_type_size,
443 const uint8_t* init_data, uint32_t init_data_size,
444 SessionType session_type) = 0;
446 // Loads the session with |web_session_id|. The CDM must respond by calling
447 // either Host::OnResolveNewSessionPromise() or Host::OnRejectPromise().
448 // If the session is not found, call Host::OnResolveNewSessionPromise()
449 // with web_session_id = NULL.
450 virtual void LoadSession(
452 const char* web_session_id, uint32_t web_session_id_length) = 0;
454 // Updates the session with |response|. The CDM must respond by calling
455 // either Host::OnResolvePromise() or Host::OnRejectPromise().
456 virtual void UpdateSession(
458 const char* web_session_id, uint32_t web_session_id_length,
459 const uint8_t* response, uint32_t response_size) = 0;
461 // Requests that the CDM close the session. The CDM must respond by calling
462 // either Host::OnResolvePromise() or Host::OnRejectPromise() when the request
463 // has been processed. This may be before the session is closed. Once the
464 // session is closed, Host::OnSessionClosed() must also be called.
465 virtual void CloseSession(
467 const char* web_session_id, uint32_t web_session_id_length) = 0;
469 // Removes any stored session data associated with this session. Will only be
470 // called for persistent sessions. The CDM must respond by calling either
471 // Host::OnResolvePromise() or Host::OnRejectPromise() when the request has
473 virtual void RemoveSession(
475 const char* web_session_id, uint32_t web_session_id_length) = 0;
477 // Requests the key IDs for keys in the session that the CDM knows are
478 // currently usable to decrypt media data. The CDM must respond by calling
479 // either Host::OnResolveKeyIdsPromise() or Host::OnRejectPromise().
480 virtual void GetUsableKeyIds(
482 const char* web_session_id, uint32_t web_session_id_length) = 0;
484 // Provides a server certificate to be used to encrypt messages to the
485 // license server. The CDM must respond by calling either
486 // Host::OnResolvePromise() or Host::OnRejectPromise().
487 virtual void SetServerCertificate(
489 const uint8_t* server_certificate_data,
490 uint32_t server_certificate_data_size) = 0;
492 // Performs scheduled operation with |context| when the timer fires.
493 virtual void TimerExpired(void* context) = 0;
495 // Decrypts the |encrypted_buffer|.
497 // Returns kSuccess if decryption succeeded, in which case the callee
498 // should have filled the |decrypted_buffer| and passed the ownership of
499 // |data| in |decrypted_buffer| to the caller.
500 // Returns kNoKey if the CDM did not have the necessary decryption key
502 // Returns kDecryptError if any other error happened.
503 // If the return value is not kSuccess, |decrypted_buffer| should be ignored
505 virtual Status Decrypt(const InputBuffer& encrypted_buffer,
506 DecryptedBlock* decrypted_buffer) = 0;
508 // Initializes the CDM audio decoder with |audio_decoder_config|. This
509 // function must be called before DecryptAndDecodeSamples() is called.
511 // Returns kSuccess if the |audio_decoder_config| is supported and the CDM
512 // audio decoder is successfully initialized.
513 // Returns kSessionError if |audio_decoder_config| is not supported. The CDM
514 // may still be able to do Decrypt().
515 // Returns kDeferredInitialization if the CDM is not ready to initialize the
516 // decoder at this time. Must call Host::OnDeferredInitializationDone() once
517 // initialization is complete.
518 virtual Status InitializeAudioDecoder(
519 const AudioDecoderConfig& audio_decoder_config) = 0;
521 // Initializes the CDM video decoder with |video_decoder_config|. This
522 // function must be called before DecryptAndDecodeFrame() is called.
524 // Returns kSuccess if the |video_decoder_config| is supported and the CDM
525 // video decoder is successfully initialized.
526 // Returns kSessionError if |video_decoder_config| is not supported. The CDM
527 // may still be able to do Decrypt().
528 // Returns kDeferredInitialization if the CDM is not ready to initialize the
529 // decoder at this time. Must call Host::OnDeferredInitializationDone() once
530 // initialization is complete.
531 virtual Status InitializeVideoDecoder(
532 const VideoDecoderConfig& video_decoder_config) = 0;
534 // De-initializes the CDM decoder and sets it to an uninitialized state. The
535 // caller can initialize the decoder again after this call to re-initialize
536 // it. This can be used to reconfigure the decoder if the configuration
538 virtual void DeinitializeDecoder(StreamType decoder_type) = 0;
540 // Resets the CDM decoder to an initialized clean state. All internal buffers
542 virtual void ResetDecoder(StreamType decoder_type) = 0;
544 // Decrypts the |encrypted_buffer| and decodes the decrypted buffer into a
545 // |video_frame|. Upon end-of-stream, the caller should call this function
546 // repeatedly with empty |encrypted_buffer| (|data| == NULL) until only empty
547 // |video_frame| (|format| == kEmptyVideoFrame) is produced.
549 // Returns kSuccess if decryption and decoding both succeeded, in which case
550 // the callee will have filled the |video_frame| and passed the ownership of
551 // |frame_buffer| in |video_frame| to the caller.
552 // Returns kNoKey if the CDM did not have the necessary decryption key
554 // Returns kNeedMoreData if more data was needed by the decoder to generate
555 // a decoded frame (e.g. during initialization and end-of-stream).
556 // Returns kDecryptError if any decryption error happened.
557 // Returns kDecodeError if any decoding error happened.
558 // If the return value is not kSuccess, |video_frame| should be ignored by
560 virtual Status DecryptAndDecodeFrame(const InputBuffer& encrypted_buffer,
561 VideoFrame* video_frame) = 0;
563 // Decrypts the |encrypted_buffer| and decodes the decrypted buffer into
564 // |audio_frames|. Upon end-of-stream, the caller should call this function
565 // repeatedly with empty |encrypted_buffer| (|data| == NULL) until only empty
566 // |audio_frames| is produced.
568 // Returns kSuccess if decryption and decoding both succeeded, in which case
569 // the callee will have filled |audio_frames| and passed the ownership of
570 // |data| in |audio_frames| to the caller.
571 // Returns kNoKey if the CDM did not have the necessary decryption key
573 // Returns kNeedMoreData if more data was needed by the decoder to generate
574 // audio samples (e.g. during initialization and end-of-stream).
575 // Returns kDecryptError if any decryption error happened.
576 // Returns kDecodeError if any decoding error happened.
577 // If the return value is not kSuccess, |audio_frames| should be ignored by
579 virtual Status DecryptAndDecodeSamples(const InputBuffer& encrypted_buffer,
580 AudioFrames* audio_frames) = 0;
582 // Called by the host after a platform challenge was initiated via
583 // Host::SendPlatformChallenge().
584 virtual void OnPlatformChallengeResponse(
585 const PlatformChallengeResponse& response) = 0;
587 // Called by the host after a call to Host::QueryOutputProtectionStatus(). The
588 // |link_mask| is a bit mask of OutputLinkTypes and |output_protection_mask|
589 // is a bit mask of OutputProtectionMethods.
590 virtual void OnQueryOutputProtectionStatus(
591 uint32_t link_mask, uint32_t output_protection_mask) = 0;
593 // Destroys the object in the same context as it was created.
594 virtual void Destroy() = 0;
597 ContentDecryptionModule_6() {}
598 virtual ~ContentDecryptionModule_6() {}
601 typedef ContentDecryptionModule_6 ContentDecryptionModule;
603 // Represents a buffer created by Allocator implementations.
606 // Destroys the buffer in the same context as it was created.
607 virtual void Destroy() = 0;
609 virtual uint32_t Capacity() const = 0;
610 virtual uint8_t* Data() = 0;
611 virtual void SetSize(uint32_t size) = 0;
612 virtual uint32_t Size() const = 0;
619 Buffer(const Buffer&);
620 void operator=(const Buffer&);
625 static const int kVersion = 6;
627 // Returns a Buffer* containing non-zero members upon success, or NULL on
628 // failure. The caller owns the Buffer* after this call. The buffer is not
629 // guaranteed to be zero initialized. The capacity of the allocated Buffer
630 // is guaranteed to be not less than |capacity|.
631 virtual Buffer* Allocate(uint32_t capacity) = 0;
633 // Requests the host to call ContentDecryptionModule::TimerFired() |delay_ms|
634 // from now with |context|.
635 virtual void SetTimer(int64_t delay_ms, void* context) = 0;
637 // Returns the current wall time in seconds.
638 virtual Time GetCurrentWallTime() = 0;
640 // Called by the CDM when a session is created or loaded and the value for the
641 // MediaKeySession's sessionId attribute is available (|web_session_id|).
642 // This must be called before OnSessionMessage() or OnSessionReady() is called
643 // for the same session. |web_session_id_length| should not include null
645 // When called in response to LoadSession(), the |web_session_id| must be the
646 // same as the |web_session_id| passed in LoadSession(), or NULL if the
647 // session could not be loaded.
648 virtual void OnResolveNewSessionPromise(
650 const char* web_session_id, uint32_t web_session_id_length) = 0;
652 // Called by the CDM when a session is updated or released.
653 virtual void OnResolvePromise(uint32_t promise_id) = 0;
655 // Called by the CDM to return a list of key IDs. The caller owns the
656 // BinaryData array and the values the elements reference.
657 virtual void OnResolveKeyIdsPromise(
659 const BinaryData* key_ids, uint32_t key_ids_length) = 0;
661 // Called by the CDM when an error occurs as a result of one of the
662 // ContentDecryptionModule calls that accept a |promise_id|.
663 // |error| must be specified, |error_message| and |system_code|
664 // are optional. Length parameters should not include null termination.
665 virtual void OnRejectPromise(
668 uint32_t system_code,
669 const char* error_message, uint32_t error_message_length) = 0;
671 // Called by the CDM when it has a message for session |web_session_id|.
672 // Length parameters should not include null termination.
673 virtual void OnSessionMessage(
674 const char* web_session_id, uint32_t web_session_id_length,
675 const char* message, uint32_t message_length,
676 const char* destination_url, uint32_t destination_url_length) = 0;
678 // Called by the CDM when there has been a change in usable keys for
679 // session |web_session_id|. |has_additional_usable_key| should be set if a
680 // key is newly usable (e.g. new key available, previously expired key has
681 // been renewed, etc.) and the browser should attempt to resume playback.
682 // Length parameter should not include null termination.
683 virtual void OnSessionUsableKeysChange(
684 const char* web_session_id, uint32_t web_session_id_length,
685 bool has_additional_usable_key) = 0;
687 // Called by the CDM when there has been a change in the expiration time for
688 // session |web_session_id|. This can happen as the result of an Update() call
689 // or some other event. If this happens as a result of a call to Update(),
690 // it must be called before resolving the Update() promise. |new_expiry_time|
691 // can be 0 to represent "undefined". Length parameter should not include
693 virtual void OnExpirationChange(
694 const char* web_session_id, uint32_t web_session_id_length,
695 Time new_expiry_time) = 0;
697 // Called by the CDM when session |web_session_id| is closed. Length
698 // parameter should not include null termination.
699 virtual void OnSessionClosed(
700 const char* web_session_id, uint32_t web_session_id_length) = 0;
702 // Called by the CDM when an error occurs in session |web_session_id|
703 // unrelated to one of the ContentDecryptionModule calls that accept a
704 // |promise_id|. |error| must be specified, |error_message| and
705 // |system_code| are optional. Length parameters should not include null
707 virtual void OnSessionError(
708 const char* web_session_id, uint32_t web_session_id_length,
710 uint32_t system_code,
711 const char* error_message, uint32_t error_message_length) = 0;
713 // The following are optional methods that may not be implemented on all
716 // Sends a platform challenge for the given |service_id|. |challenge| is at
717 // most 256 bits of data to be signed. Once the challenge has been completed,
718 // the host will call ContentDecryptionModule::OnPlatformChallengeResponse()
719 // with the signed challenge response and platform certificate. Length
720 // parameters should not include null termination.
721 virtual void SendPlatformChallenge(
722 const char* service_id, uint32_t service_id_length,
723 const char* challenge, uint32_t challenge_length) = 0;
725 // Attempts to enable output protection (e.g. HDCP) on the display link. The
726 // |desired_protection_mask| is a bit mask of OutputProtectionMethods. No
727 // status callback is issued, the CDM must call QueryOutputProtectionStatus()
728 // periodically to ensure the desired protections are applied.
729 virtual void EnableOutputProtection(uint32_t desired_protection_mask) = 0;
731 // Requests the current output protection status. Once the host has the status
732 // it will call ContentDecryptionModule::OnQueryOutputProtectionStatus().
733 virtual void QueryOutputProtectionStatus() = 0;
735 // Must be called by the CDM if it returned kDeferredInitialization during
736 // InitializeAudioDecoder() or InitializeVideoDecoder().
737 virtual void OnDeferredInitializationDone(StreamType stream_type,
738 Status decoder_status) = 0;
740 // Creates a FileIO object from the host to do file IO operation. Returns NULL
741 // if a FileIO object cannot be obtained. Once a valid FileIO object is
742 // returned, |client| must be valid until FileIO::Close() is called. The
743 // CDM can call this method multiple times to operate on different files.
744 virtual FileIO* CreateFileIO(FileIOClient* client) = 0;
751 // Represents a decrypted block that has not been decoded.
752 class DecryptedBlock {
754 virtual void SetDecryptedBuffer(Buffer* buffer) = 0;
755 virtual Buffer* DecryptedBuffer() = 0;
757 // TODO(tomfinegan): Figure out if timestamp is really needed. If it is not,
758 // we can just pass Buffer pointers around.
759 virtual void SetTimestamp(int64_t timestamp) = 0;
760 virtual int64_t Timestamp() const = 0;
764 virtual ~DecryptedBlock() {}
776 virtual void SetFormat(VideoFormat format) = 0;
777 virtual VideoFormat Format() const = 0;
779 virtual void SetSize(cdm::Size size) = 0;
780 virtual cdm::Size Size() const = 0;
782 virtual void SetFrameBuffer(Buffer* frame_buffer) = 0;
783 virtual Buffer* FrameBuffer() = 0;
785 virtual void SetPlaneOffset(VideoPlane plane, uint32_t offset) = 0;
786 virtual uint32_t PlaneOffset(VideoPlane plane) = 0;
788 virtual void SetStride(VideoPlane plane, uint32_t stride) = 0;
789 virtual uint32_t Stride(VideoPlane plane) = 0;
791 virtual void SetTimestamp(int64_t timestamp) = 0;
792 virtual int64_t Timestamp() const = 0;
796 virtual ~VideoFrame() {}
799 // Represents decrypted and decoded audio frames. AudioFrames can contain
800 // multiple audio output buffers, which are serialized into this format:
802 // |<------------------- serialized audio buffer ------------------->|
803 // | int64_t timestamp | int64_t length | length bytes of audio data |
805 // For example, with three audio output buffers, the AudioFrames will look
808 // |<----------------- AudioFrames ------------------>|
809 // | audio buffer 0 | audio buffer 1 | audio buffer 2 |
812 virtual void SetFrameBuffer(Buffer* buffer) = 0;
813 virtual Buffer* FrameBuffer() = 0;
815 // The CDM must call this method, providing a valid format, when providing
816 // frame buffers. Planar data should be stored end to end; e.g.,
817 // |ch1 sample1||ch1 sample2|....|ch1 sample_last||ch2 sample1|...
818 virtual void SetFormat(AudioFormat format) = 0;
819 virtual AudioFormat Format() const = 0;
823 virtual ~AudioFrames() {}
828 #endif // CDM_CONTENT_DECRYPTION_MODULE_H_