W3C home > Mailing lists > Public > public-webrtc@w3.org > February 2012

Data API Proposal aligned to WebSocket

From: Adam Bergkvist <adam.bergkvist@ericsson.com>
Date: Wed, 22 Feb 2012 17:32:52 +0100
Message-ID: <4F4518B4.7010605@ericsson.com>
To: "public-webrtc@w3.org" <public-webrtc@w3.org>
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.

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. 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 ...
};
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;
     readonly attribute unsigned long bufferedAmount;

     // 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
Received on Wednesday, 22 February 2012 16:38:29 UTC

This archive was generated by hypermail 2.3.1 : Monday, 23 October 2017 15:19:27 UTC