createDataChannel() API

We're getting ready to do a major update to the Mozilla DataChannel 
implementation to reflect the results of the Interim and recent IETF 
meeting.  I need a quick answer on the direction to take in the update, 
as we have some compatibility breaks we must do (wireline protocol 
changes) and want to minimize the pain for developers.

In this change, per the presentation at the Interim that I hope you all 
paid attention to (but I think everyone was busy worrying about the 
wireline issues), createDataChannel() would change from:

    channel = peerconnection.createDataChannel(label, dictionary_object)
to
    channel = peerconnection.createDataChannel(label, protocol, 
dictionary_object)

Note that this breaks backwards compatibility.  Now that there are 
existing (if experimental) applications using this API in both Chrome 
and Firefox, this will impact those developers (though it's an easy 
update - but knowing which one to use isn't, since we don't version the 
API, and I don't want people to have to sniff UAs).

I propose instead moving the protocol field into the dictionary (and so 
people who don't care about it can easily ignore it).

In related news, to support external negotiation I propose adding these 
fields to the dictionary (and I'll note that the dictionary is woefully 
out of date, supporting in the spec only "reliable")

/* If either maxRetransmitTime or maxRetransmitNum are set, it's
    unreliable, else it's a reliable channel.  If both are set it's an
    error.  outOfOrderAllowed can be used with any type of channel.  The
    equivalent of UDP is { outOfOrderAllowed: true, maxRetransmitNum: 0 }.
    The TCP equivalent is {}.
    preset is true if the channel is being externally negotiated, and no
    wireline OpenRequest message should be sent.  If preset is true, stream
    can be optionally used to set a specific SCTP stream to use.  If it's
    false but preset is true, then the application should read the 'stream'
    attribute from the returned DataChannel and convey it to the other end
    to pass in via the DataChannelInit dictionary.
  */
dictionary DataChannelInit {
   boolean outOfOrderAllowed;
   unsigned short maxRetransmitTime;
   unsigned short maxRetransmitNum;
   DOMString protocol;
   boolean preset;
   unsigned short stream;
};

Should we include 'reliable' in the dictionary for back-compatibility?
Firefox has not implemented 'reliable' up until now, we've had the above
(minus protocol and the new negotiation support). If included, it would be
shorthand for {} or { outOfOrderAllowed:true, maxRetransmitNum:0 }
(depending on value). We'd need verbiage about mixing it with the detailed
members however.

And I added to the DataChannel webidl:

   readonly attribute DOMString protocol;
   readonly attribute unsigned short stream;

and had previously added:

   readonly attribute boolean ordered;

And the question of the existing 'reliable' attribute would come up 
here, though we
can synthesize a value for it from the dictionary values easily per 
above.  We could expose the

-- 
Randell Jesup
randell-ietf@jesup.org

Received on Friday, 29 March 2013 13:02:57 UTC