RE: PROPOSAL: New signature for getUserMedia and callbacks

"error handling to be in the default path for developers" seems like a worthwhile goal. I don't think error handling should be optional (IMO it's bad design to ignore errors), and while this does not make it mandatory for the developer to code for it, it does avoid a degree of the code fragmentation that results from multiple callbacks.

Thanks,
Bryan Sullivan 

-----Original Message-----
From: Anant Narayanan [mailto:anant@mozilla.com] 
Sent: Friday, March 30, 2012 2:25 AM
To: public-media-capture@w3.org
Subject: PROPOSAL: New signature for getUserMedia and callbacks

What
--
Change the signature of getUserMedia to:

navigator.getUserMedia(options, callback);

where option is a dictionary of type UserMediaOptions (currently video and audio are the two allowed keys, but easily extensible to include UserMediaConstraints/Hints), and callback is a single callback invoked in cases of either error or success.

Why
--
We've been wanting to steer away from using the two callback approach for a while now. There are multiple ways to do this. One proposal described using events, eliminating callbacks altogether. The usefulness of events in the case of getUserMedia was questioned (as it is not a DOM object), and the only useful property remaining would be that of multiple listeners.

As we could not reach consensus on that (and events vs. callbacks is more of a style issue that I am willing to compromise on), I propose we use a node.js style callback to achieve the initial goal of moving away from the two callbacks.

The main reason for not wanting to use two callbacks has been discussed before, the WebAPI design community in general has been moving away from this pattern. In summary, we want error handling to be in the default path for developers, and two callbacks always makes the error callback be considered optional. By using a single callback, even if the developer doesn't check the value of 'err' in their handler, an exception would have a reasonable stack trace (this is not true if the developer doesn't provide a failure callback and an error occurs).

How
--
This changes the signature of getUserMedia to:

navigator.getUserMedia(options, function(err, stream) {
...
});

i.e. there is only 1 callback, invoked with two arguments err and stream. If an error occurs, err will be set to an appropriate value (which I propose should be string, a separate mail on that will follow) and stream will be undefined. If the call succeeded, err will be undefined and stream will be the MediaStream requested.

Look forward to your feedback!

-Anant

Received on Friday, 30 March 2012 17:40:24 UTC