Alternative data API

(Strictly in a contributor role):

I've written up this text on how the data API could look if we stayed 
with the model of the August 23rd version of the webrtc spec 
(<http://dev.w3.org/2011/webrtc/editor/webrtc-20110823.html>) where the 
data API was directly on the PeerConnection object ("send" method).

It is much less advanced than what Justin has proposed, the main 
advantages are Web Socket alignment (but I think Justin is aligning the 
DataStream's to WS right now) and less work to specify as much can be 
inherited from Web Sockets. I don't know how much of the Web Socket 
implementation that could be re-used.

I attach some text that could be part of the webrtc rec.

I don't have a strong view on what direction to take, all I want to do 
is to point out that this approach could be selected if we want to 
minimize work now (and possibly extend later if there is demand); the 
drawback is less functionality (at least from day one).

Stefan


================================================================

1 Intro
=======
This is a proposal for the data channel API of PeerConnection. It 
adheres closely to the Web Sockets API 
(http://dev.w3.org/html5/websockets/).

2 Function
==========
When initiating a new PeerConnection a data channel is always offered. 
If the other end (e.g. a gateway) does not support data, no data channel 
will be available (as this part of the offer is rejected).

If data is supported, the application can send data to the peer using 
the “send” method. Different types of data can be sent. The receiving 
application is notified about incoming data by a MessageEvent [1]. The 
“send” method can take different input data, for the time being data of 
types “DOMString”, “ArrayBuffer” ([2]) and “blob” ([3]) is supported. 
Support for Stream ([4]) can be added as soon as Stream is added to the 
File API ([5]) spec.

3 Changes to PeerConnection
============================

interface PeerConnection {
     [...]
     // messaging
     [TreatNonCallableAsNull] attribute Function? onmessage;
     void send(DOMString? data);
     void send(Blob data);
     void send(ArrayBuffer data);

     readonly attribute unsigned long bufferedAmount; //buffered amount

     [...]
};

4 Example
=========

// standard setup
var pc = new PeerConnection('TURNS example.net', sendSignalingChannel);

//in this case, the PeerConnection offer just offers data (no audio, 
video or DTMF)
// PeerConnection eventually enters the “ACTIVE” state

//setup what to do when a message arrives
pc.onmessage = function (evt) {
      do something using evt.data
}


// send a string
pc.send("foo");
// the message is delivered; remote end gets a MessageEvent and handles 
the incoming message

5 Discussion
============
Should a readonly “protocol” attribute be added? Allows app to check 
what protocol (and if data is supported at all) has been negotiated. On 
the other hand, the app could easily check by sending a special message 
and expect an answer (e.g. send "ping", if you receive "pong" things are 
working).

6 Compatibility with use cases
==============================
Use cases for data has been listed in two different documents, [6] and [7].

In the first document, use case is "Quick updates of the game state".

In the second one the use cases are

* U-C 1 A real-time game where position and object state information is 
sent via one or more unreliable data channels. Note that at any time 
there may be no media channels, or all media channels may be inactive.

* U-C 2 Non-critical state updates about a user in a video chat or 
conference, such as Mute state.

* U-C 3 A real-time game where critical state information needs to be 
transferred, such as control information.  Typically this would be 
datagrams. Such a game may have no media channels, or they may be 
inactive at any given time, or may only be added due to in-game actions.

* U-C 4 Non-realtime file transfers between people chatting.

* U-C 5 Realtime text chat while talking with an individual or with 
multiple people in a conference.

* U-C 6 Renegotiation of the set of media streams in the PeerConnection.

At first glance it seems the use cases can be solved with the proposed API.


7 Future extensions
===================
Extensions that can be made if there is demand.

7.1 "Status API"
--------------------
A read only attribute “protocol” as for Web Socket could be added. This 
would enable the application to determine what protocol that has been 
negotiated for data (and if the other end point rejected the data offer 
the response will be “null”). Perhaps this API could be incorporated in 
a PeerConnection status API that lists all things that have been 
negotiated (audio session, video session, data session).

7.2 Add options to send methods, add send Stream
------------------------------------------------
Options to the send methods could be added (e.g. to allow prioritizing 
between messages, and to allow sending unreliably).

interface PeerConnection {
     [...]
     // messaging
     [TreatNonCallableAsNull] attribute Function? onmessage;
     void send(DOMString? data, optional DataOptions options);
     void send(Blob data, optional DataOptions options);
     void send(ArrayBuffer data, optional DataOptions options);
     void send(Stream data, optional DataOptions options);

     readonly attribute unsigned long bufferedAmount; //buffered amount

     [...]
};

dictionary DataOptions {
     octet priority = 0;
     boolean reliable = true;
}

7.3 Channel messaging
---------------------
If there is a demand, channel messaging as outlined in [8] can be added 
at a later stage.


8 Refs
======
[1] http://dev.w3.org/html5/postmsg/
[2] http://www.khronos.org/registry/typedarray/specs/latest/
[3] http://dev.w3.org/2006/webapi/FileAPI/
[4] http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm
[5] http://dev.w3.org/2006/webapi/FileAPI/
[6] 
http://datatracker.ietf.org/doc/draft-ietf-rtcweb-use-cases-and-requirements/?include_text=1
[7] http://datatracker.ietf.org/doc/draft-jesup-rtcweb-data/?include_text=1
[8] http://dev.w3.org/html5/postmsg/#channel-messaging