WebRTC 1.0: Real-time Communication Between Browsers
W3C Editor's Draft 20 September 2011
- This version:
- http://dev.w3.org/2011/webrtc/editor/webrtc.html
- Latest published version:
- http://www.w3.org/TR/webrtc/
- Latest editor's draft:
- http://dev.w3.org/2011/webrtc/editor/webrtc.html
- Previous version:
- none
- Editors:
- Adam Bergkvist, Ericsson
- Daniel C. Burnett, Voxeo
- Cullen Jennings, Cisco
- Anant Narayanan, Mozilla
Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:
© Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.
All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group are under the following Copyright:
© 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. Document use rules apply.
For the entire publication on the W3C site the liability and trademark rules apply.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document was published by the Web Real-Time Communications Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-webrtc@w3.org@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
3. Stream API
3.1 Introduction
The MediaStream interface is used to
represent streams of media data, typically (but not necessarily) of audio and/or video
content, e.g. from a local camera or a remote site. The data from a MediaStream object does not necessarily have a canonical
binary form; for example, it could just be "the video currently coming from the user's
video camera". This allows user agents to manipulate media streams in whatever fashion
is most suitable on the user's platform.
Each MediaStream object can represent zero
or more tracks, in particular audio and video tracks. Tracks can contain multiple
channels of parallel data; for example a single audio track could have nine channels of
audio data to represent a 7.2 surround sound audio track.
Each track represented by a MediaStream
object has a corresponding MediaStreamTrack object.
A MediaStream object has an input and an
output. The input depends on how the object was created: a LocalMediaStream object generated by a getUserMedia() call, for instance, might take
its input from the user's local camera, while a MediaStream created by a PeerConnection object will take as input the data received
from a remote peer. The output of the object controls how the object is used, e.g. what
is saved if the object is written to a file, what is displayed if the object is used in
a video element, or indeed what is transmitted to a remote peer if the
object is used with a PeerConnection
object.
Each track in a MediaStream object can be
disabled, meaning that it is muted in the object's output. All tracks are initially
enabled.
A MediaStream can be
finished,
indicating that its inputs have forever stopped providing data. When a MediaStream object is finished, all its tracks are muted
regardless of whether they are enabled or disabled.
The output of a MediaStream object must
correspond to the tracks in its input. Muted audio tracks must be replaced with
silence. Muted video tracks must be replaced with blackness.
A MediaStream object's output can be
"forked" by creating a new MediaStream object
from it using the MediaStream() constructor. The new MediaStream object's input is the output of the object from
which it was created, with any disabled tracks removed, and its output is therefore at
most a subset of that "parent" object. (Merely muted tracks are not removed, so the
tracks do not change when the parent is finished.) When such a fork's parent finishes,
the fork is also said to have finished.
This can be used, for instance, in a video-conferencing scenario to display the
local video from the user's camera and microphone in a local monitor, while only
transmitting the audio to the remote peer (e.g. in response to the user using a "video
mute" feature).
When a track in a MediaStream parent is disabled, any MediaStreamTrack objects corresponding to the tracks in
any MediaStream objects that were created from
parent are disassociated from any track, and must not be reused for
tracks again. If a disabled track in a MediaStream parent is re-enabled, from
the perspective of any MediaStream objects that
were created from parent it is a new track and thus new
MediaStreamTrack objects must be created
for the tracks that correspond to the re-enabled track.
The LocalMediaStream interface is used
when the user agent is generating the stream's data (e.g. from a camera or streaming it
from a local video file). It allows authors to control individual tracks during the
generation of the content, e.g. to allow the user to temporarily disable a local camera
during a video-conference chat.
When a LocalMediaStream object is being
generated from a local file (as opposed to a live audio/video source), the user agent
should stream the data from the file in real time, not all at once. This reduces the
ease with which pages can distinguish live video from pre-recorded video, which can
help protect the user's privacy.
3.2 Interface definitions
3.2.5 BlobCallback
[Callback=FunctionOnly, NoInterfaceObject]
interface BlobCallback {
void handleEvent (Blob blob);
};
3.2.5.1 Methods
handleEvent- Def TBD
| Parameter | Type | Nullable | Optional | Description |
|---|
| blob | Blob | ✘ | ✘ | |
No exceptions.
3.2.6 URL
Note that the following is actually only a partial interface, but ReSpec does
not yet support that.
interface URL {
static DOMString createObjectURL (MediaStream stream);
};
3.2.6.1 Methods
createObjectURL-
Mints a Blob URL to refer to the given MediaStream.
When the createObjectURL() method is called
with a MediaStream argument, the user agent
must return a unique Blob URL for the given MediaStream. [FILE-API]
For audio and video streams, the data exposed on that stream must be in a format
supported by the user agent for use in audio and video
elements.
A Blob URL is the same as what the
File API specification calls a Blob URI, except that anything in the
definition of that feature that refers to File and Blob
objects is hereby extended to also apply to MediaStream and LocalMediaStream objects.
| Parameter | Type | Nullable | Optional | Description |
|---|
| stream | MediaStream | ✘ | ✘ | |
No exceptions.
3.3 Examples
This sample code exposes a button. When clicked, the button is disabled and the
user is prompted to offer a stream. The user can cause the button to be re-enabled by
providing a stream (e.g. giving the page access to the local camera) and then
disabling the stream (e.g. revoking that access).
<input type="button" value="Start" onclick="start()" id="startBtn">
<script>
var startBtn = document.getElementById('startBtn');
function start() {
navigator.getUserMedia('audio,video', gotStream);
startBtn.disabled = true;
}
function gotStream(stream) {
stream.onended = function () {
startBtn.disabled = false;
}
}
</script>
This example allows people to record a short audio message and upload it to the
server. This example even shows rudimentary error handling.
<input type="button" value="⚫" onclick="msgRecord()" id="recBtn">
<input type="button" value="◼" onclick="msgStop()" id="stopBtn" disabled>
<p id="status">To start recording, press the ⚫ button.</p>
<script>
var recBtn = document.getElementById('recBtn');
var stopBtn = document.getElementById('stopBtn');
function report(s) {
document.getElementById('status').textContent = s;
}
function msgRecord() {
report('Attempting to access microphone...');
navigator.getUserMedia('audio', gotStream, noStream);
recBtn.disabled = true;
}
var msgStream, msgStreamRecorder;
function gotStream(stream) {
report('Recording... To stop, press to ◼ button.');
msgStream = stream;
msgStreamRecorder = stream.record();
stopBtn.disabled = false;
stream.onended = function () {
msgStop();
}
}
function msgStop() {
report('Creating file...');
stopBtn.disabled = true;
msgStream.onended = null;
msgStream.stop();
msgStreamRecorder.getRecordedData(msgSave);
}
function msgSave(blob) {
report('Uploading file...');
var x = new XMLHttpRequest();
x.open('POST', 'uploadMessage');
x.send(blob);
x.onload = function () {
report('Done! To record a new message, press the ⚫ button.');
recBtn.disabled = false;
};
x.onerror = function () {
report('Failed to upload message. To try recording a message again, press the ⚫ button.');
recBtn.disabled = false;
};
}
function noStream() {
report('Could not obtain access to your microphone. To try again, press the ⚫ button.');
recBtn.disabled = false;
}
</script>
This example allows people to take photos of themselves from the local video
camera.
<article>
<style scoped>
video { transform: scaleX(-1); }
p { text-align: center; }
</style>
<h1>Snapshot Kiosk</h1>
<section id="splash">
<p id="errorMessage">Loading...</p>
</section>
<section id="app" hidden>
<p><video id="monitor" autoplay></video> <canvas id="photo"></canvas>
<p><input type=button value="📷" onclick="snapshot()">
</section>
<script>
navigator.getUserMedia('video user', gotStream, noStream);
var video = document.getElementById('monitor');
var canvas = document.getElementById('photo');
function gotStream(stream) {
video.src = URL.getObjectURL(stream);
video.onerror = function () {
stream.stop();
};
stream.onended = noStream;
video.onloadedmetadata = function () {
canvas.width = video.videoWidth;
canvas.height = video.videoHeight;
document.getElementById('splash').hidden = true;
document.getElementById('app').hidden = false;
};
}
function noStream() {
document.getElementById('errorMessage').textContent = 'No camera available.';
}
function snapshot() {
canvas.getContext('2d').drawImage(video, 0, 0);
}
</script>
</article>
4. Peer-to-peer connections
A PeerConnection allows two users to
communicate directly, browser-to-browser. Communications are coordinated via a
signaling channel provided by script in the page via the server, e.g. using
XMLHttpRequest.
Calling "new PeerConnection(configuration,
signalingCallback)" creates a PeerConnection object.
The configuration string gives the address of a STUN or TURN
server to use to establish the connection. [STUN] [TURN]
The allowed formats for this string are:
- "
TYPE 203.0.113.2:3478"
-
Indicates a specific IP address and port for the server.
- "
TYPE relay.example.net:3478""
-
Indicates a specific host and port for the server; the user agent will look up
the IP address in DNS.
- "
TYPE example.net""
-
Indicates a specific domain for the server; the user agent will look up the IP
address and port in DNS.
The "TYPE" is one of:
STUN- Indicates a STUN server
STUNS- Indicates a STUN server that is to be contacted using a TLS session.
TURN- Indicates a TURN server
TURNS- Indicates a TURN server that is to be contacted using a TLS session.
The signalingCallback argument is a method that will be invoked
when the user agent needs to send a message to the other host over the signaling
channel. When the callback is invoked, convey its first argument (a string) to the
other peer using whatever method is being used by the Web application to relay
signaling messages. (Messages returned from the other peer are provided back to the
user agent using the processSignalingMessage()
method.)
A PeerConnection object has an associated
PeerConnection signaling
callback, a PeerConnection ICE
Agent, a PeerConnection data UDP media
stream, a PeerConnection
readiness state and an ICE started flag. These
are initialized when the object is created.
When the PeerConnection() constructor is invoked, the
user agent must run the following steps. This algorithm has a synchronous
section (which is triggered as part of the event loop algorithm).
Steps in the synchronous section are marked with ⌛.
-
Let serverConfiguration be the constructor's first
argument.
-
Let signalingCallback be the constructor's second
argument.
-
Let connection be a newly created PeerConnection object.
-
Create an ICE Agent and let connection's PeerConnection ICE Agent be that ICE
Agent. [ICE]
-
If serverConfiguration contains a U+000A LINE FEED (LF)
character or a U+000D CARRIAGE RETURN (CR) character (or both), remove all
characters from serverConfiguration after the first such
character.
-
Split serverConfiguration on spaces to obtain configuration
components.
-
If configuration components has two or more components, and
the first component is a case-sensitive match for one of the following
strings:
- "
STUN"
- "
STUNS"
- "
TURN"
- "
TURNS"
...then run the following substeps:
-
Let server type be STUN if the first component of
configuration components is 'STUN' or
'STUNS', and TURN otherwise (the first component of
configuration components is "TURN" or
"TURNS").
-
Let secure be true if the first component of configuration components is "STUNS" or
"TURNS", and false otherwise.
-
Let host be the contents of the second component of
configuration components up to the character before the
first U+003A COLON character (:), if any, or the entire string otherwise.
-
Let port be the contents of the second component of
configuration components from the character after the first
U+003A COLON character (:) up to the end, if any, or the empty string
otherwise.
-
Configure the PeerConnection ICE Agent's STUN or
TURN server as follows:
- If server type is STUN, the server is a STUN server.
Otherwise, server type is TURN and the server is a TURN
server.
- If secure is true, the server is to be contacted
using TLS-over-TCP, otherwise, it is to be contacted using UDP.
- The IP address, host name, or domain name of the server is host.
- The port to use is port. If this is the empty string,
then only a domain name is configured (and the ICE Agent will use DNS SRV
requests to determine the IP address and port).
- The long-term username for the STUN or TURN server is the ASCII serialization of the
entry script's origin; the long-term password is
the empty string.
If the given IP address, host name, domain name, or port are invalid, then
the user agent must act as if no STUN or TURN server is configured.
-
Let the connection's PeerConnection signaling
callback be signalingCallback.
-
Set connection's PeerConnection readiness state
to NEW (0).
-
Set connection's ICE started
flag to false.
-
Let connection's PeerConnection data UDP media
stream be a new data UDP media stream.
-
Let connection's localStreams attribute be an empty
read-only MediaStream array.
[WEBIDL]
-
Let connection's remoteStreams attribute be an empty
read-only MediaStream array.
[WEBIDL]
-
Return connection, but continue these steps
asynchronously.
-
Await a stable state. The synchronous section consists
of the remaining steps of this algorithm. (Steps in synchronous sections are marked with ⌛.)
-
⌛ If connection's ICE started
flag is still false, start the PeerConnection ICE Agent and send the
initial offer. The initial offer must include a media description for the PeerConnection data UDP media
stream, marked as "sendrecv", and for all the streams in localStreams (marked as "sendonly").
[ICE] [SDPOFFERANSWER]
-
⌛ Let connection's ICE started
flag be true.
-
⌛ If connection's PeerConnection readiness state
is still NEW (0), then queue a task that
sets it to NEGOTIATING (1) and then fires a simple event named connecting at the PeerConnection object.
When a PeerConnection is required to send
SDP offers or answers, the user agent must follow these steps:
-
Let sdp be the SDP offer or answer to be sent. [SDPOFFERANSWER]
-
Let message be the concatenation of the string "SDP", a U+000A LINE FEED (LF) character, and sdp,
in that order.
-
Queue a task to invoke the PeerConnection signaling
callback with message as its first argument and the
PeerConnection as its second
argument.
All streams represented by MediaStream
objects must be marked as "sendonly" by the peer that initially adds the stream to the
session. The PeerConnection API does not
support bidirectional ("sendrecv") audio or video media streams. [SDPOFFERANSWER]
User agents may negotiate any codec and any resolution, bitrate, or other quality
metric. User agents are encouraged to initially negotiate for the native resolution of
the stream. For streams that are then rendered (using a video element),
user agents are encouraged to renegotiate for a resolution that matches the rendered
display size.
Starting with the native resolution means that if the Web application
notifies its peer of the native resolution as it starts sending data, and the peer
prepares its video element accordingly, there will be no need for a
renegotiation once the stream is flowing.
All SDP media descriptions for streams represented by MediaStream objects must include a label attribute
("a=label:") whose value is the value of the MediaStream object's label attribute.
[SDP] [SDPLABEL]
PeerConnections must not generate any
candidates for media streams whose media descriptions do not have a label attribute
("a=label:"). [ICE] [SDP] [SDPLABEL]
When a user agent starts receiving media for a component and a candidate was
provided for that component by a PeerConnection, the user agent must follow these
steps:
-
Let connection be the PeerConnection expecting this media.
-
If there is already a MediaStream object
for the media stream to which this component belongs, then associate the component
with that media stream and abort these steps. (Some media streams have multiple
components; this API does not expose the role of these individual components in
ICE.)
-
Create a MediaStream object to represent
the media stream. Set its label attribute to the value of the SDP Label
attribute for that component's media stream.
-
Queue a task to run the following substeps:
-
If the connection's PeerConnection readiness
state is CLOSED (3), abort these steps.
-
Add the newly created MediaStream
object to the end of connection's remoteStreams array.
-
Fire a stream event named addstream with the newly created
MediaStream object at the connection object.
When a PeerConnection finds that a stream
from the remote peer has been removed (its port has been set to zero in a media
description sent on the signaling channel), the user agent must follow these steps:
-
Let connection be the PeerConnection associated with the stream being
removed.
-
Let stream be the MediaStream object that represents the media stream being
removed, if any. If there isn't one, then abort these steps.
-
By definition, stream is now finished.
A task is thus queued to update stream and fire an
event.
-
Queue a task to run the following substeps:
-
If the connection's PeerConnection readiness
state is CLOSED (3), abort these steps.
-
Remove stream from connection's
remoteStreams array.
-
Fire a stream event named removestream with stream at the connection object.
The task source for the tasks listed
in this section is the networking task source.
To prevent network sniffing from allowing a fourth party to
establish a connection to a peer using the information sent out-of-band to the other
peer and thus spoofing the client, the configuration information should always be
transmitted using an encrypted connection.
4.1 PeerConnection
[Constructor (in DOMString configuration, in SignalingCallback signalingCallback)]
interface PeerConnection {
void processSignalingMessage (DOMString message);
const unsigned short NEW = 0;
const unsigned short NEGOTIATING = 1;
const unsigned short ACTIVE = 2;
const unsigned short CLOSED = 3;
readonly attribute unsigned short readyState;
void send (DOMString text);
void addStream (MediaStream stream);
void removeStream (MediaStream stream);
readonly attribute MediaStream[] localStreams;
readonly attribute MediaStream[] remoteStreams;
void close ();
attribute Function? onconnecting;
attribute Function? onopen;
attribute Function? onmessage;
attribute Function? onaddstream;
attribute Function? onremovestream;
};
4.1.1 Attributes
localStreams of type array of MediaStream, readonly-
Returns a live array containing the streams that the user agent is currently
attempting to transmit to the remote peer (those that were added with addStream()).
Specifically, it must return the read-only MediaStream array that the attribute was set to when the
PeerConnection's constructor ran.
No exceptions.
onaddstream of type Function, nullable- This event handler, of event handler event
type
addstream, must be supported by all objects
implementing the PeerConnection
interface.No exceptions.
onconnecting of type Function, nullable- This event handler, of event handler event
type
connecting, must be supported by all
objects implementing the PeerConnection
interface.No exceptions.
onmessage of type Function, nullable- This event handler, of event handler event
type
message, must be supported by all objects
implementing the PeerConnection
interface.No exceptions.
onopen of type Function, nullable- This event handler, of event handler event
type
open, must be supported by all objects
implementing the PeerConnection
interface.No exceptions.
onremovestream of type Function, nullable- This event handler, of event handler event
type
removestream, must be supported by all
objects implementing the PeerConnection
interface.No exceptions.
readyState of type unsigned short, readonly-
The readyState attribute
must return the PeerConnection object's
PeerConnection readiness
state, represented by a number from the following list:
PeerConnection . NEW
(0)- The object was just created, and no networking has yet occurred.
PeerConnection . NEGOTIATING (1)- The user agent is attempting to establish a connection.
PeerConnection . ACTIVE (2)- The connection is as good as it's going to get.
PeerConnection . CLOSED (3)- The connection is closed.
No exceptions.
remoteStreams of type array of MediaStream, readonly-
Returns a live array containing the streams that the user agent is currently
receiving from the remote peer.
Specifically, it must return the read-only MediaStream array that the attribute was set to when the
PeerConnection's constructor ran.
This array is updated when addstream and removestream events are fired.
No exceptions.
4.1.2 Methods
addStream-
Attempts to starting sending the given stream to the remote peer.
When the other peer starts sending a stream in this manner, an addstream event is fired at the
PeerConnection object.
When the addStream() method is
invoked, the user agent must run the following steps:
-
Let stream be the method's argument.
-
If the PeerConnection object's
PeerConnection readiness
state is CLOSED (3), throw an
INVALID_STATE_ERR exception.
-
If stream is already in the PeerConnection object's localStreams object, then abort
these steps.
-
Add stream to the end of the PeerConnection object's localStreams object.
-
Return from the method.
-
Have the PeerConnection add a
media stream for stream the next time the user agent
provides a stable state. Any other
pending stream additions and removals must be processed at the same time.
| Parameter | Type | Nullable | Optional | Description |
|---|
| stream | MediaStream | ✘ | ✘ | |
No exceptions.
close-
When the close() method is invoked,
the user agent must run the following steps:
-
If the PeerConnection object's
PeerConnection readiness
state is CLOSED (3), throw an
INVALID_STATE_ERR exception.
-
Destroy the PeerConnection
ICE Agent, abruptly ending any active ICE processing and any active
streaming, and releasing any relevant resources (e.g. TURN permissions).
-
Set the object's PeerConnection readiness
state to CLOSED (3).
The localStreams and remoteStreams objects remain in the
state they were in when the object was closed.
No parameters.
No exceptions.
processSignalingMessage-
When a message is relayed from the remote peer over the signaling channel is
received by the Web application, pass it to the user agent by calling the
processSignalingMessage()
method.
The order of messages is important. Passing messages to the user agent in a
different order than they were generated by the remote peer's user agent can
prevent a successful connection from being established or degrade the connection's
quality if one is established.
When the processSignalingMessage() method is invoked, the user agent must
run the following steps:
-
Let message be the method's argument.
-
Let connection be the PeerConnection object on which the method was
invoked.
-
If connection's PeerConnection readiness
state is CLOSED (3), throw an
INVALID_STATE_ERR exception.
-
If the first four characters of message are not
"SDP" followed by a U+000A LINE FEED (LF) character, then
abort these steps. (This indicates an error in the signaling channel
implementation. User agents may report such errors to their developer consoles
to aid debugging.)
Future extensions to the PeerConnection interface might use other prefix
values to implement additional features.
-
Let sdp be the string consisting of all but the first
four characters of message.
-
If connection's ICE started
flag is true, then pass sdp to the PeerConnection ICE Agent as a
subsequent offer or answer, to be interpreted as appropriate given the current
state of the ICE Agent, and abort these steps. [ICE]
-
The ICE started flag is false. Start the
PeerConnection ICE Agent
and pass it sdp as the initial offer from the other peer;
the ICE Agent will then (asynchronously) construct the initial answer and
transmit it as described above.
If there is a remotely-initiated data UDP media
stream in the initial offer, and it has an encryption key advertised in its
media description that is 16 bytes long, then that is the PeerConnection data UDP
media stream.
After the initial answer has been sent, the ICE Agent must add all the
streams in localStreams to the session, as
described above. [ICE]
-
Let connection's ICE started
flag be true.
-
Queue a task that sets connection's
PeerConnection readiness
state to NEGOTIATING (1) and then
fires a simple event named
connecting at the PeerConnection object.
When a PeerConnection ICE
Agent completes ICE processing (even if there are no active streams), the user
agent must queue a task that sets the PeerConnection object's PeerConnection readiness state
to ACTIVE (2) and then fires a simple event named open at the
PeerConnection object.
When a PeerConnection ICE
Agent restarts ICE processing for any reason (e.g. because a peer is adding or
removing a stream), the user agent must queue a task that sets the
PeerConnection object's PeerConnection readiness state
to NEGOTIATING (1) and then fires a simple event named connecting at the PeerConnection object.
| Parameter | Type | Nullable | Optional | Description |
|---|
| message | DOMString | ✘ | ✘ | |
No exceptions.
removeStream-
Steps sending the given stream to the remote peer.
When the other peer stops sending a stream in this manner, a removestream event is fired at the
PeerConnection object.
When the removeStream() method
is invoked, the user agent must run the following steps:
-
Let stream be the method's argument.
-
If the PeerConnection object's
PeerConnection readiness
state is CLOSED (3), throw an
INVALID_STATE_ERR exception.
-
If stream is not in the PeerConnection object's localStreams object, then abort
these steps.
-
Remove stream from the PeerConnection object's localStreams object.
-
Return from the method.
-
Have the PeerConnectionremove the
media stream for stream the next time the user agent
provides a stable state. Any other
pending stream additions and removals must be processed at the same time.
| Parameter | Type | Nullable | Optional | Description |
|---|
| stream | MediaStream | ✘ | ✘ | |
No exceptions.
send-
Attempts to send the given text to the remote peer. This uses UDP, which is
inherently unreliable; there is no guarantee that every message will be
received.
When a message sent in this manner from the other peer is received, a
message event is fired at the
PeerConnection object.
The maximum length of text is 504 bytes after encoding the
string as UTF-8; attempting to send a payload greater than 504 bytes results in an
INVALID_ACCESS_ERR exception.
When the send() method is invoked, the
user agent must run the following steps:
-
Let message be the method's first argument.
-
If the PeerConnection object's
PeerConnection readiness
state is CLOSED (3), throw an
INVALID_STATE_ERR exception.
-
Let data be message encoded as
UTF-8. [UTF-8]
-
If data is longer than 504 bytes, throw an
INVALID_ACCESS_ERR exception and abort these steps.
-
If the PeerConnection's PeerConnection data UDP
media stream is not an active data
UDP media stream, abort these steps. No message is sent.
-
If the user agent is rate-limiting packets sent using this API, and sending
the data packet at this time would exceed the limit, then abort these steps.
User agents may report this to the user, e.g. in a development console.
-
Transmit a data packet to a
peer using the PeerConnection's
PeerConnection
data UDP media stream with data as the message.
| Parameter | Type | Nullable | Optional | Description |
|---|
| text | DOMString | ✘ | ✘ | |
No exceptions.
4.1.3 Constants
ACTIVE of type unsigned short- The ICE Agent has concluded ICE processing. If any media streams were
successfully negotiated, any relevant media is streaming.
CLOSED of type unsigned short- The
close() method has been invoked. NEGOTIATING of type unsigned short- The ICE Agent is actively performing ICE processing.
NEW of type unsigned short- The object was just created and its ICE Agent has not yet been started.
PeerConnection implements EventTarget;
4.2 SignalingCallback
[Callback=FunctionOnly, NoInterfaceObject]
interface SignalingCallback {
void handleEvent (DOMString message, PeerConnection source);
};
4.2.1 Methods
handleEvent- Def TBD
No exceptions.
4.3 Examples
When two peers decide they are going to set up a connection to each other, they
both go through these steps. The STUN/TURN server configuration describes a server
they can use to get things like their public IP address or to set up NAT traversal.
They also have to send data for the signaling channel to each other using the same
out-of-band mechanism they used to establish that they were going to communicate in
the first place.
// the first argument describes the STUN/TURN server configuration
var local = new PeerConnection('TURNS example.net', sendSignalingChannel);
local.signalingChannel(...); // if we have a message from the other side, pass it along here
// (aLocalStream is some LocalMediaStream object)
local.addStream(aLocalStream); // start sending video
function sendSignalingChannel(message) {
... // send message to the other side via the signaling channel
}
function receiveSignalingChannel (message) {
// call this whenever we get a message on the signaling channel
local.signalingChannel(message);
}
local.onaddstream = function (event) {
// (videoElement is some <video> element)
videoElement.src = URL.getObjectURL(event.stream);
};