Real-Time Communication with WebRTC (2014)

Appendix A. WebRTC 1.0 APIs

This Appendix provides a summary of the W3C WebRTC APIs.

RTCPeerConnection API

An RTCPeerConnection allows two users to communicate directly, browser to browser.

Configuration

Table A-1. RTCConfiguration dictionary members

Name	Type	Default	Description
iceServers	sequence<RTCIceServer>		An array containing URIs of servers available to be used by ICE, such as STUN and TURN servers.
iceTransports	RTCIceTransports	“all”	Indicates which candidates the ICE engine is allowed to use.
requestIdentity	RTCIdentityOption	“ifconfigured”	See the requestIdentity member of the RTCOfferAnswerOptions dictionary.

Table A-2. RTCIceServer dictionary members

Name	Type	Description
credential	DOMString	If this RTCIceServer object represents a TURN server, then this attribute specifies the credentials to use with that TURN server.
urls	(DOMString or sequence<DOMString>)	STUN or TURN URI(s) as defined in [STUN-URI] and [TURN-URI] or other URI types.
username	DOMString	If this RTCIceServer object represents a TURN server, then this attribute specifies the username to use with that TURN server.

Table A-3. RTCIceTransports enumeration values

Value	Description
none	The ICE engine must not send or receive any packets at this point.
relay	The ICE engine must only use media relay candidates such as candidates passing through a TURN server. This can be used to reduce leakage of IP addresses in certain use cases.
all	The ICE engine may use any type of candidates when this value is specified.

Constructor

This is the RTCPeerConnection constructor:

§ RTCPeerConnection(configuration)

Methods

Here are the RTCPeerConnection methods:

§ createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options)|

§ createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferAnswerOptions options)

§ setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

§ setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

§ updateIce (RTCConfiguration configuration)

§ addIceCandidate (RTCIceCandidate candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

§ getConfiguration ()

§ getLocalStreams ()

§ getRemoteStreams ()

§ getStreamById (DOMString streamId)

§ addStream (MediaStream stream)

§ removeStream (MediaStream stream)

§ close ()

Attributes

Table A-4. RTCPeerConnection attributes

Access property	Type	Name
readonly	RTCSessionDescription	remoteDescription
readonly	RTCSignalingState	signalingState
readonly	RTCIceGatheringState	iceGatheringState
readonly	RTCIceConnectionState	iceConnectionState
	EventHandler	onnegotiationneeded
	EventHandler	onicecandidate
	EventHandler	onsignalingstatechange
	EventHandler	onaddstream
	EventHandler	onremovestream
	EventHandler	oniceconnectionstatechange

State Definition

Table A-5. RTCSignalingState

Value	Description
stable	There is no offer/answer exchange in progress. This is also the initial state in which case the local and remote descriptions are empty.
have-local-offer	A local description, of type “offer,” has been successfully applied.
have-remote-offer	A remote description, of type “offer,” has been successfully applied.
have-local-pranswer	A remote description of type “offer” has been successfully applied and a local description of type “pranswer” has been successfully applied.
have-remote-pranswer	A local description of type “offer” has been successfully applied and a remote description of type “pranswer” has been successfully applied.
closed	The connection is closed.

Table A-6. RTCIceGatheringState

Value	Description
new	The object was just created, and no networking has occurred yet.
gathering	The ICE engine is in the process of gathering candidates for this RTCPeerConnection.
complete	The ICE engine has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

Table A-7. RTCIceConnectionState

Value	Description
new	The ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied.
checking	The ICE Agent has received remote candidates on at least one component, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering.
connected	The ICE Agent has found a usable connection for all components but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering.
completed	The ICE Agent has finished gathering and checking and found a connection for all components.
failed	The ICE Agent is finished checking all candidate pairs and failed to find a connection for at least one component. Connections may have been found for some components.
disconnected	Liveness checks have failed for one or more components. This is more aggressive than failed, and may trigger intermittently (and resolve itself without action) on a flaky network.
closed	The ICE Agent has shut down and is no longer responding to STUN requests.

Peer-to-Peer Data API

The Peer-to-Peer Data API lets a web application send and receive generic application data peer-to-peer. The API for sending and receiving data models the behavior of WebSockets.

§ Method:

RTCDataChannel

createDataChannel ([TreatNullAs=EmptyString] DOMString label, optional RTCDataChannelInit dataChannelDict)

§ Attribute:

EventHandler

ondatachannel

Interface RTCDataChannel Interface Methods

Table A-8. Methods

Return type	Name
void	close()
void	send(DOMString data)
void	send(Blob data)
void	send(ArrayBuffer data)
void	send(ArrayBufferView data)

RTCDataChannel Interface Attributes

Table A-9. Attributes

Access property	Type	Name
readonly	DOMString	label
readonly	boolean	ordered
readonly	unsigned?	maxRetransmitTime
readonly	unsigned?	maxRetransmits
readonly	DOMString	protocol
readonly	attribute	negotiated
readonly	unsigned short	id
readonly	RTCDataChannelState	readyState
readonly	unsigned long	bufferedAmount
	EventHandler	onopen
	EventHandler	onerror
	EventHandler	onclose
	EventHandler	onmessage
	DOMString	binaryType

Table A-10. RTCDataChannelInit dictionary

Name	Type	Description
id	unsigned short	Overrides the default selection of ID for this channel.
maxRetransmitTime	unsigned short	Limits the time during which the channel will retransmit data if not successfully delivered.
maxRetransmits	unsigned short	Limits the number of times a channel will retransmit data if not successfully delivered.
negotiated	boolean	Defaults to false. The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a corresponding RTCDataChannel object. If set to true, it is up to the application to negotiate the channel and create an RTCDataChannel object with the same ID as the other peer.
ordered	boolean	Defaults to true. If set to false, data is allowed to be delivered out of order. The default value of true guarantees that data will be delivered in order.
protocol	DOMString	Defaults to "". Subprotocol name used for this channel.

Table A-11. RTCDataChannelState enumeration values

Value	Description
connecting	The user agent is attempting to establish the underlying data transport. This is the initial state of an RTCDataChannel object created with createDataChannel().
open	The underlying data transport is established and communication is possible. This is the initial state of an RTCDataChannel object dispatched as a part of an RTCDataChannelEvent.
closing	The procedure to close down the underlying data transport has started.
closed	The underlying data transport has been closed or could not be established.