RTCPeerConnection.onnegotiationneeded
This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
The RTCPeerConnection.onnegotiationneeded
property is an EventHandler
which specifies a function which is called to handle the negotiationneeded
event when it occurs on an RTCPeerConnection
instance. This event is fired when a change has occurred which requires session negotiation.
The most common scenario in which this will happen is at the beginning of a connection. After using createOffer()
to create a new offer and setting it as the description of the local end of the connection by calling setLocalDescription()
, the browser will, when it's ready, fire negotiationneeded
to let you know it's ready for you to begin negotiating the connection. That's when it's time to send the offer along through the signaling server.
Syntax
RTCPeerConnection.onnegotiationneeded = eventHandler;
Value
This should be set to a function you provide which is passed a single parameter: an Event
object containing the negotiationneeded
event. There's no additional information provided in the event; anything you need, you can get by examining the properties of the RTCPeerConnection
.
Example
This example, derived from the example in Signaling and video calling, establishes a handler for negotiationneeded
events to handle creating an offer, configuring the local end of the connection, and sending the offer to the remote peer.
pc.onnegotiationneeded = function() { pc.createOffer().then(function(offer) { return pc.setLocalDescription(offer); }) .then(function() { // Send the offer to the remote peer through the signaling server }); }) .catch(reportError); }
First, it creates the offer by calling createOffer()
. When that succeeds, the offer is passed into setLocalDescription()
to set the local description for the connection. Once that's succeeded in turn, the offer can be sent to the signaling server for delivery to the remote peer.
Specifications
Specification | Status | Comment |
---|---|---|
WebRTC 1.0: Real-time Communication Between Browser The definition of 'RTCPeerConnection.onnegotiationneeded' in that specification. |
Working Draft | Initial specification. |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | 24 (24) [1] | No support | (Yes) | ? |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | ? | 24.0 (24) [1] | No support | ? | ? |
[1] Though this property is not prefixed, the RTCPeerConnection
interface it belongs to was until Firefox 44.
See also
- The
negotiationneeded
event and its type,Event
.
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/rtcpeerconnection/onnegotiationneeded