W3C home > Mailing lists > Public > public-html-media@w3.org > June 2012

[EME] Object-oriented API design proposal #2 (using a MediaKeySession constructor)

From: David Dorwin <ddorwin@google.com>
Date: Fri, 29 Jun 2012 14:15:21 -0700
Message-ID: <CAHD2rsge2BVkDMjxyTXoTc8y9hmkd505g2+QMMNh3u0uZCmYdQ@mail.gmail.com>
To: public-html-media@w3.org
This is an alternate proposal for a session object-based design that uses a
MediaKeySession constructor instead of creating the object using a method
on the media element. See the related thread [1] for rational. This
proposal uses the second variant from that email.

This proposal is mostly the same as the previous proposal [2] but with
differences related to construction of the session object and association
of it with a media element. Please refer to the previous thread [2] for
additional background since I am only highlighting the differences here.

*Summary of Changes from Previous Proposal*
The main differences from the previous proposal [2] are:

   - generateKeyRequest() is removed from HTMLMediaElement.
   - MediaKeySession has a constructor used to create sessions.
   - addKeySession() is added to HTMLMediaElement to associate the
   constructed session with a media element.


Notable implications:

   - This proposal does not support implicit reuse of session objects when
   the initData is the same or similar because a new object is always created.
   - All errors are reported through the error event. That is, there is
   never a null object resulting from the constructor.
   - MIME type ("type") must be explicitly specified at construction so
   that the object knows how to interpret "initData".

*
*
*Changes from Previous Proposal*
Only the constructor and new method on the media element are different from
the previous proposa [2]. I've colored these lines red below.

There is a plain text version of the updated interface definitions at very
end of this email.
*
*


partial interface HTMLMediaElement {
  // Adds optional 'keySystem' parameter.
  DOMString canPlayType
<#1383a1251bcff681_1383a07710268a0d_dom-canplaytype>(in DOMString
type, in DOMstring? keySystem
<#1383a1251bcff681_1383a07710268a0d_key-system>);

  // key sessions
  void addKeySession
<#1383a1251bcff681_1383a07710268a0d_dom-addkeysession>(in
MediaKeySession
<#1383a1251bcff681_1383a07710268a0d_dom-mediakeysession> session);
};
[Constructor <#1383a1251bcff681_1383a07710268a0d_dom-media-key-session-constructor>
(in DOMString keySystem
<#1383a1251bcff681_1383a07710268a0d_key-system>, in DOMString? type,
in Uint8Array? initData)]interface MediaKeySession : EventTarget
<#1383a1251bcff681_1383a07710268a0d_dom-eventtarget> {
  // error state
  readonly attribute MediaKeyError
<#1383a1251bcff681_1383a07710268a0d_dom-mediakeyerror>? error
<#1383a1251bcff681_1383a07710268a0d_dom-error>;

  // session properties
  readonly attribute DOMString keySystem
<#1383a1251bcff681_1383a07710268a0d_dom-keysystem>;
  readonly attribute DOMString sessionId
<#1383a1251bcff681_1383a07710268a0d_dom-sessionid>;

  // session operations
  void addKey <#1383a1251bcff681_1383a07710268a0d_dom-addkey>(in
Uint8Array key);
  void close <#1383a1251bcff681_1383a07710268a0d_dom-close>();
};

partial interface HTMLSourceElement {
             attribute DOMString keySystem
<#1383a1251bcff681_1383a07710268a0d_dom-sourcekeysystem>;
};

*
*
*Example Use*
This is the same as in the related thread [1].

  function handleNeedKey(event) {
    var session = new MediaKeySession(keySystem, mimeType, initData);
    if (session) {
      session.onkeymessage = handleKeyMessage;
      session.onkeyerror = handleKeyError;
      var video = event.target;
      video.addKeySession(session);
    }
  }

*Open Questions*
This section reflects the impact of this proposal on the Open Questions
listed in the previous proposal [2]. There is also one new question (#8)
specific to this proposal.

   1. *Yes.* That is what this proposal does.
   2. *No.* This proposal does not support reuse of session objects.
   3. No change.
   4. No change.
   5. No change.
   6. No change. However, sharing of MediaKeySession objects would be more
   natural in this design.
   7. No change.
   8. *[NEW]* How can we avoid specifying MIME type or simplify the process
   of providing it for applications?
      1. The "initData" parameter would be ambiguous without a container
      type.
      2. We could automate the process of providing it by doing one of the
      following:
         1. Add "type" to MediaKeyNeededEvent, which also contains the
         initData.
         2. Expose "type"/"currentType"/"srcType" attribute from the
HTMLMediaElement.
         Would this be generally useful as well?



[1] http://lists.w3.org/Archives/Public/public-html-media/2012Jun/0134.html
[2] http://lists.w3.org/Archives/Public/public-html-media/2012Jun/0136.html



========== Begin Plain Text Version of Changes Section ==========

partial interface HTMLMediaElement {
  // Adds optional 'keySystem' parameter.
  DOMString canPlayType(in DOMString type, in DOMstring? keySystem);

  // key sessions
  void addKeySession(in MediaKeySession session);
};

[Constructor (in DOMString keySystem, in DOMString? type, in Uint8Array?
initData)]
interface MediaKeySession : EventTarget {
  // error state
  readonly attribute MediaKeyError? error;

  // session properties
  readonly attribute DOMString keySystem;
  readonly attribute DOMString sessionId;

  // session operations
  void addKey(in Uint8Array key);
  void close();
};

partial interface HTMLSourceElement {
             attribute DOMString keySystem;
};
Received on Friday, 29 June 2012 21:16:09 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:32:56 UTC