Re: Data API Proposal aligned to WebSocket

On 2/22/2012 11:32 AM, Adam Bergkvist wrote:
> Hi
>
> I got a task from the WebRTC chairs and editors to work some more with
> the Data API, taking Justins proposal as a starting point, meet what
> most people seem to want
> (http://lists.w3.org/Archives/Public/public-webrtc/2012Feb/0153.html)
> from the API and align with the Web Socket API as far as possible.
> Comments and feedback are greatly appreciated.

Thanks for doing this; I was going to take a whack at just this thing 
this week!  Much easier now.

> A DataChannel object is bi-directional data channel that is decoupled
> from the MediaStream concept. I.e., there are no local or remote
> DataChannels since data can be written to, and read from the same
> object. When a DataChannel is created at one end of a PeerConnection, an
> event, with the corresponding DataChannel, is dispatched on the other
> end. There's no need to remove a DataChannel object from it's associated
> PeerConnection; the close() method disposes the channel similar to
> WebSocket.

Yeah, I'm still of two minds on the unidirectional/bidirectional thing. 
  It's certainly a simpler API if it's bidirectional (one object type 
instead of two), even if many uses don't use the opposite direction.  It 
does potentially slow down channel creation, as you probably need a 1.5 
RTT setup instead of .5 or 1.0 RTT (depending on if you wanted an 
"onopened"), and you have to handle stream-id 'glare'. It requires more 
'networking' code to handle all this.  I prefer unidirectional - the 
mapping to streams is much simpler, but I realize the typical 
"network-style" API is at odds with what a typical JS programmer would 
expect, so that's an argument for this type of API.

Not a big deal, though.

More comments below:

> The DataChanelInit dictionary is used to configure a
> DataChannel at creation time; it will be extended as we expose more
> configuration possibilities.
>
> Some examples:
>
> // Simple example how to create a DataChannel, send and receive data.
>
> var chan = peerConn.createDataChannel("mylabel");
>
> chan.onmessage = function (evt) {
> // use evt.data
> };
>
> chan.send("hello");
>
> -----
>
> // Example of to handle the case when a remote peer creates a DataChannel
>
> peerConn.ondatachannel = function (evt) {
> var chan = evt.channel;
>
> chan.onmessage = function (evt) {
> // use evt.data
> };
>
> chan.onclose = function () {
> // remote side closed the data channel
> };
> };
>
> ----
>
> Below are the IDLs of this API.
>
> *** Changes to PeerConnection ***
>
> interface PeerConnection {
> ...
>
> DataChannel createDataChannel(DOMString? label, optional
> DataChannelInit? dataChannelDict);
>
> attribute Function? ondatachannel;
> ...
> };
>
>
> *** DataChannel ***
>
> interface DataChannel {
> readonly attribute DOMString label;
>
> readonly attribute boolean reliable;
> readonly attribute long priority;
> // ... extend here ...

readonly attribute boolean outoforder; // default to true for unreliable?
readonly attribute unsigned long retryTime; // for partially reliable

...others perhaps

> };
> DataChannel implements AbstractMessenger;
>
> interface AbstractMessenger {
> // ready state
> const unsigned short CONNECTING = 0;
> const unsigned short OPEN = 1;
> const unsigned short CLOSING = 2;
> const unsigned short CLOSED = 3;
> readonly attribute unsigned short readyState;

See discussions on the list about readyState-type attributes (though I 
realize this mirrors existing use).

> readonly attribute unsigned long bufferedAmount;

Should we let them read the PMTU?

> // networking
> [TreatNonCallableAsNull] attribute Function? onopen;
> [TreatNonCallableAsNull] attribute Function? onerror;
> [TreatNonCallableAsNull] attribute Function? onclose;
> void close([Clamp] optional unsigned short code, optional DOMString
> reason);
>
> // messaging
> [TreatNonCallableAsNull] attribute Function? onmessage;
> attribute DOMString binaryType;
> void send(DOMString data);
> void send(ArrayBuffer data);
> void send(Blob data);
> };
>
>
> *** Dictionaries and Events ***
>
> dictionary DataChannelInit {
> boolean reliable;
> long priority;
> // ... extend here ...
> };
>
> [Constructor(DOMString type, optional DataChannelEventInit eventInitDict)]
> interface DataChannelEvent : Event {
> readonly attribute DataChannel? channel;
> };
>
> dictionary DataChannelEventInit : EventInit {
> DataChannel? channel;
> };
>
> /Adam
>
>


-- 
Randell Jesup
randell-ietf@jesup.org

Received on Wednesday, 22 February 2012 22:52:54 UTC