Re: Move to de-facto error reporting

     I'm in favor of considering the second proposal :) I don't think it 
would break much user code, just the initial event listener 
registration. I wouldn't group *all* events into a single object but 
rather group related events into their own event listeners. For example:

  * onstreamadded, onstreamremoved
  * onstatechanged, onicechange, onopen, onnegotiationneeded
  * onicecandidate

     The main benefit is readability. These events typically need to 
share state between one another. When the user listens to one event he 
typically should also listen to the others. You could also conceivably 
store state in the event listener object as opposed to passing it into 
each function.

Gili

On 08/01/2013 6:46 AM, Harald Alvestrand wrote:
> Top-posting because it's a generic comment....
>
> I see Travis making 2 almost unrelated points:
>
> - Errors should be unified, we shouldn't invent new forms of error for 
> each API.
> - Errors should be events dispatched to an object representing the 
> operation-in-progress, not callbacks.
>
> I agree on the first one. I'm happy to accept any reasonable proposal 
> for such an unification.
>
> I disagree on the second one. This is another one of those "throw away 
> all the users' code and tell them to start over" changes; we should 
> only do that when there's a *clear* benefit to the users.
>
> Disclosure: I did the first version of the stats API in the "new 
> pattern" and switched to the "old pattern" for consistency across the 
> PeerConnection API. I know it's possible to write both versions with 
> equivalent functionality, because I've done it.
>
> But I don't see an advantage to the "operation object" pattern that is 
> compelling enough for us to tell the users to start over.
>
>                Harald
>
> On 12/20/2012 10:05 PM, Travis Leithead wrote:
>> [Cross-posting for visibility]
>>
>> I'd like to suggest that we refactor our error handling behavior 
>> among all three WebRTC primary specs: WebRTC, Media Capture and 
>> Streams, and the Recording API. I'd like to move to the error model 
>> in use in DOM4/File API/IndexedDb and HTML5's Media Elements.
>>
>> I pointed out in another thread 
>> (http://lists.w3.org/Archives/Public/public-media-capture/2012Dec/0163.html) 
>> that the WebRTC/Media Capture/Recording API specs are using an 
>> error-notification model that is not based on the model being used by 
>> other specs in the WebApps and HTML working group-namely we're basing 
>> our model off of the Geolocation spec's pattern, rather than that of 
>> the DOM4/File API/IndexedDb/HTML5 pattern.
>>
>> The new pattern has only been around for a little over a year, so I 
>> don't think we can be blamed for not noticing/applying it earlier.
>>
>> To summarize the differences in the patterns:
>> * The Geolocation pattern is to have a callback/event which is 
>> provided with an Error object which has a field which reports the 
>> name of the error (the error name and the exception names are usually 
>> the same).
>> * The new pattern is to use a DOMError-based "error" attribute on the 
>> target object and use a normal vanilla "error" event to raise 
>> awareness that this state-attribute has been set.
>>
>> Here's how the Geolocation pattern plays out in the WebRTC, Media 
>> Capture and Streams, and Recording API proposals:
>>
>> An example from WebRTC's doc: RTCPeerConnection.createOffer says:
>> void createOffer(RTCSessionDescriptionCallback successCallback,
>>                   RTCPeerConnectionErrorCallback failureCallback, ...)
>>
>> Where RTCPeerConnectionErrorCallback will get an RTCError, and the 
>> RTCError has a "name" and a "message"
>>
>> This pattern is repeated elsewhere in getUserMedia: 
>> NavigatorUserMediaErrorCallback has a NavigatorUserMediaError with a 
>> "code".
>> and now in the Recording Proposal [1]: onrecordingerror gets a 
>> RecordingError object which has a "name" and a "message"
>>
>> As you can see, this pattern needlessly complicates the web platform 
>> by having a bunch of objects that basically provide the exact same 
>> functionality.
>>
>> In the WebApps and HTML working groups, they have also seen this 
>> proliferation, and decided to unify under a new pattern for providing 
>> asynchronous error notifications. In the new pattern, there is an 
>> error state which is maintained by an object, and an event that fires 
>> to inform the application to check the object's error state.
>>
>> DOMError is the object that consolidates the functionality of 
>> RTCError, NavigatorUserMediaError, and RecordingError. It also 
>> consolidated similiarly proposed error objects in the File API, 
>> Indexed Db specs. The DOMError object is defined in DOM4 [2].
>>
>> Here's how it looks in FileReader [3]:
>>
>> interface FileReader {
>>     readonly attribute DOMError error;
>>              attribute Function? onerror;
>>     ...
>> }
>>
>> Here it is for Indexed Db transaction request objects [4]:
>>
>> interface IDBRequest {
>>     readonly attribute DOMError error;
>>              attribute Function? onerror;
>>     ...
>> }
>>
>> Here's how it's used in HTML5 [5] (which uses codes, unfortunately, 
>> so it's based on the model before DOMError came around, and has now 
>> been widely implemented so it can't be changed):
>> Interface HTMLMediaElement {
>>     readonly attribute MediaError? error;
>>     ...
>> }
>> And an onerror handler defined in the super-interface HTMLElement.
>>
>> I'd like to propose that we re-use this concept for our specs. The 
>> specific changes would apply to:
>>
>> WebRTC spec:
>> * RTCPeerConnection interface would get a DOMError error attribute, 
>> and an onerror EventHandler. The following APIs would need to be 
>> adjusted/simplified to remove the failureCallback parameter:
>>    - createOffer
>>    - createAnswer
>>    - setLocalDescription
>>    - setRemoteDescription
>>    - getStats
>>
>> Media Capture and Streams spec:
>> * MediaStream interface would get a DOMError error attribute, and an 
>> onerror EventHandler. The Following APIs would be adjusted to remove 
>> the errorCallback:
>>    - getUserMedia
>>
>> Recording API spec:
>> * MediaRecorder interface would get a DOMError error attribute. This 
>> interface already has an onrecordingerror handler, and it would be 
>> simplified to not carry the error state and behave like other normal 
>> event objects.
>>
>>
>> [1] 
>> http://dvcs.w3.org/hg/dap/raw-file/tip/media-stream-capture/RecordingProposal.html
>> [2] 
>> http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-domerror
>> [3] http://dev.w3.org/2006/webapi/FileAPI/#dfn-error-codes
>> [4] 
>> http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#request-api
>> [5] 
>> http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#mediaerror
>>
>>
>
>