Bug 18531 - Consider renaming addKey method
Summary: Consider renaming addKey method
Status: RESOLVED FIXED
Alias: None
Product: HTML WG
Classification: Unclassified
Component: Encrypted Media Extensions (show other bugs)
Version: unspecified
Hardware: All All
: P2 normal
Target Milestone: FPWD
Assignee: David Dorwin
QA Contact: HTML WG Bugzilla archive list
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2012-08-10 18:38 UTC by Mark Watson
Modified: 2013-01-12 03:02 UTC (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Mark Watson 2012-08-10 18:38:01 UTC
The addKey method can be used for more than just providing a key. Specifically it can be used for
- providing a key
- providing a license
- updating a license or other CDM session state

As a result the addKey name is confusing.

In general, the purpose of this method is to provide a message to the CDM that updates the session state in some CDM-specific way. With the object-oriented model, sessions are explicitly represented by session objects and addKey is a method on that object. With that context we could rename the method to something as simple as update() - it is a method on the session object so the implication is that it updates the session somehow.
Comment 1 Adrian Bateman [MSFT] 2012-08-28 20:30:09 UTC
Agree on addKey potentially being confusing. How about addData()?

Assigned to Mark to follow-up on the mailing list.
Comment 2 Mark Watson 2012-10-15 19:34:03 UTC
Mailing list consensus is to go with update()
Comment 3 Yang Sun 2012-10-19 06:55:25 UTC
I think key or license is very similar, and even you want to update a license or key, you still need to provide a new key or license.addKey() is very clear about proivide key or license to CDM, what the confusion comes from?

So I think addKey() is clear enough to express its functionality, using update() seems confusing me more than addKey(), because app developer will not clearly know what can be "update" by update().

What's more, in webrtc, we have updateIce(), we also use update, but we know that we are update configuration of ICE agent.






(In reply to comment #0)
> The addKey method can be used for more than just providing a key.
> Specifically it can be used for
> - providing a key
> - providing a license
> - updating a license or other CDM session state
> 
> As a result the addKey name is confusing.
> 
> In general, the purpose of this method is to provide a message to the CDM
> that updates the session state in some CDM-specific way. With the
> object-oriented model, sessions are explicitly represented by session
> objects and addKey is a method on that object. With that context we could
> rename the method to something as simple as update() - it is a method on the
> session object so the implication is that it updates the session somehow.
Comment 4 Mark Watson 2012-10-19 19:09:17 UTC
(In reply to comment #3)
> I think key or license is very similar, and even you want to update a
> license or key, you still need to provide a new key or license.addKey() is
> very clear about proivide key or license to CDM, what the confusion comes
> from?

This method can be used to update the CDM state in a CDM-specific way. For example, a CDM supporting heartbeat might require regular updates which modify the expiry time of the license. Is this a new key ? or a new license ? or an update to an existing license ? That depends on the CDM.

Another example would be secure proof of key release, where this method will be used to provide an acknowledgement from the server that a proof of key release message has been received. This is certainly not a new key or new license, but it does cause an update to the CDM internal state.

> 
> So I think addKey() is clear enough to express its functionality, using
> update() seems confusing me more than addKey(), because app developer will
> not clearly know what can be "update" by update().
> 
> What's more, in webrtc, we have updateIce(), we also use update, but we know
> that we are update configuration of ICE agent.
> 
> 
> 
> 
> 
> 
> (In reply to comment #0)
> > The addKey method can be used for more than just providing a key.
> > Specifically it can be used for
> > - providing a key
> > - providing a license
> > - updating a license or other CDM session state
> > 
> > As a result the addKey name is confusing.
> > 
> > In general, the purpose of this method is to provide a message to the CDM
> > that updates the session state in some CDM-specific way. With the
> > object-oriented model, sessions are explicitly represented by session
> > objects and addKey is a method on that object. With that context we could
> > rename the method to something as simple as update() - it is a method on the
> > session object so the implication is that it updates the session somehow.
Comment 5 David Dorwin 2012-12-11 17:00:08 UTC
No further comments at TPAC 2012. Please make the change.
Comment 6 David Dorwin 2013-01-12 03:02:24 UTC
Changed in https://dvcs.w3.org/hg/html-media/rev/ac33b782ee55.

We never discussed the parameter name, which is still |key|. It could be |message|, but I would rather avoid ambiguity for that word. Changing the API is the important part, so I consider this fixed for FPWD. We can change the parameter name at any time.