Original text:
application that gathering is occurring through an event.  Then, when each new ICE candidate becomes available, the ICE Agent will supply it to the application via an additional event; these candidates will <del> also automatically be added to the local session description. Finally, when all candidates have been gathered, an event will be dispatched to signal that the gathering process is complete. </del>  Note that gathering phases only gather the candidates needed by new/recycled/restarting m= lines; other m= lines continue to use provisional answers, and any previous call leg will be terminated. At some point, the application will end the setup process, perhaps with a timer; at this point, the application could reapply the <del> existing remote description as a final answer. </del>  3.6.2. this, we introduce the concept of "rollback". A rollback discards any proposed changes to the session, returning <del> the state machine to the stable state, and setting the modified local and/or remote description back to their previous values.  Any resources or candidates that were allocated by the abandoned local description are discarded; any media that is received will be processed according to the previous local and remote descriptions. Rollback can only be used to cancel proposed changes; there is no support for rolling back from a stable state to a previous stable state.  Note that this implies that once the answerer has performed setLocalDescription with his answer, this cannot be rolled back. </del>  A rollback is performed by supplying a session description of type "rollback" with empty contents to either setLocalDescription or successfully handle scenarios where the application wants to offer to change from one media format to a different, incompatible format, the PeerConnection must be able to simultaneously support use of both the <del> old and new local descriptions (e.g. support codecs that exist in both descriptions) until a final answer is received, at which point the PeerConnection can fully adopt the new local description, or roll back to the old description if the remote side denied the change. </del>  This API indirectly controls the candidate gathering process.  When a local description is supplied, and the number of transports currently description, the PeerConnection will create transports as needed and begin gathering candidates for them. <del> If setRemoteDescription was previous called with an offer, and </del>  setLocalDescription is called with an answer (provisional or final), and the media directions are compatible, and media are available to send, this will result in the starting of media transmission. 4.1.7. <del> The localDescription method returns a copy of the current local configuration, i.e. what was most recently passed to setLocalDescription, plus any local candidates that have been generated by the ICE Agent. </del>  <del> [[OPEN ISSUE: Do we need to expose accessors for both the current and proposed local description? https://github.com/rtcweb-wg/jsep/ issues/16]] A null object will be returned if the local description has not yet been established. </del>  4.1.8. <del> The remoteDescription method returns a copy of the current remote configuration, i.e. what was most recently passed to setRemoteDescription, plus any remote candidates that have been supplied via processIceMessage. [[OPEN ISSUE: Do we need to expose accessors for both the current and proposed remote description? https://github.com/rtcweb-wg/jsep/ issues/16]] </del>  <del> A null object will be returned if the remote description has not yet been established. </del>  4.1.9.  The canTrickleIceCandidates property indicates whether the remote side supports receiving trickled candidates.  There are three potential values: Trickle on initial offers and Full Trickle on subsequent interactions with a Trickle ICE-compatible agent. <del> 4.1.10. </del>  The setConfiguration method allows the global configuration of the PeerConnection, which was initially set by constructor parameters, to may result in a change to media state if it results in connectivity being established. <del> 4.1.11. </del>  The addIceCandidate method provides a remote candidate to the ICE <del> Agent, which, if parsed successfully, will be added to the remote description according to the rules defined for Trickle ICE. Connectivity checks will be sent to the new candidate. </del>  This call will result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity

Reviewer comments:
I left out the unqualified /, since these are redundant, and only exist in the WebRTC spec as a convenience and for backwards compatibility.
I need to read this carefully at some point but just quickly scanning the diff .. it looks workable. Thanks.
LGTM. I didn't look to see if there were other references to the local/remote desc that need to be updated, but I assume that you already scanned carefully.
I think everything should be covered now. I've gone through twice looking at every place the word "description" is used. Though when talking about rollback, I think "return to the previous description" sounds less confusing than "return to the current description", so I left that wording alone.
LGTM
JSEP S 4.1.7 and 4.1.8 read: " TODO: Do we need to expose accessors for both the current and proposed local description?" and " TODO: Do we need to expose accessors for both the current and proposed remote description?"
DC plan - we add these to W3c spec.
Discussed in DC: Values will be created for surfacing both proposed and current descriptions. Ultimately, this is a matter for the WebRTC group, where the names can be selected and decisions like what to do with existing values can be made.
This is bug URL
Can we close this ?
I would prefer to keep it until the text is written
For the purposes of this comment, let's call the needed APIs .currentLocalDesc and .pendingLocalDesc. On the offerer side, setLocal(desc) updates .pendingLocalDesc to be (desc). On the offerer side, setLocal(rollback) updates .pendingLocalDesc to be NULL. On the answerer side, setRemote(desc) updates .pendingRemoteDesc to be (desc). On the answerer side, setRemote(rollback) updates .pendingRemoteDesc to NULL. On the answerer side, setLocal(desc) updates .currentLocalDesc to be (desc), .currentRemoteDesc to .pendingRemoteDesc, and .pendingRemoteDesc to NULL. On the offerer side, setRemote(desc) updates .currentRemoteDesc to be (desc), .currentLocalDesc to be .pendingLocalDesc, and .pendingLocalDesc to be NULL. Unfortunately, both .pending and .current have slightly different semantics than the existing .local/.remoteDescription properties, so I think we would need to retain .local/remote for now. However, they could be polyfilled as propX = (pendingX) ? pendingX : currentX.
This looks good and need to be clear that some while the pending is out, you need to receive on both current and pending.
Not done yet but started putting this into PC spec on branch URL - have a look and see if it is going the right direction
(Moved my comment to PR)
Hi NAME , why not a simpler 2-arg rather than 3-arg solution? For the purposes of this comment, let's call the needed APIs .localDescription and .stableLocalDescription. On the offerer side, setLocal(desc) updates .localDescription to be (desc). On the offerer side, setLocal(rollback) updates .localDescription to be .stableLocalDescription. On the answerer side, setRemote(desc) updates .remoteDescription to be (desc). On the answerer side, setRemote(rollback) updates .remoteDescription to be .stableRemoteDescription. On the answerer side, setLocal(desc) updates .localDescription and .stableLocalDescription to be (desc), and .stableRemoteDescription to be .remoteDescription. On the offerer side, setRemote(desc) updates .remoteDescription and .stableRemoteDescription to be (desc), and .stableLocalDescription to be .localDescription.
I see what you are trying to do, and I think this would work OK, but the fact that the semantics of .localDescription/.remoteDescription mutate depending on the current state make this confusing. (IOW, sometimes localDescription is the stable desc, sometimes it is the pending desc). I think .current/.pending is the clearest approach, but open to other opinions.
I would argue the semantics don't mutate and their availability transcend state: is the last-set description always is the last negotiated description always
From the point of view of a programmer using the API, I think that what I want to get is the SDP to do with the current negotiation, and the old SDP that I would roll back to. I tend to think of it as old and new. During transition time, the stuff in use is the combination of the old offer/answer pair plus the new offer. The stuff .current/.pending is close enough to this and seems fine to me.
Do you realize you just used "current" to refer to "pending", and "old" to refer to "current"? You want to roll back to the last stable state.
Uh, I used current to refer to old and pending to refer to new.
My point is that these relative words "current" and "pending" are not well-defined, whereas "stable" is. KISS.
I'm not sure stable is a word that makes as much sense as you might hope to developers. It is not used int he SDP or Offer/Answer spec. Anyways, I don't feel strongly about this. None of the names are perfect.
URL
Forgetting about the accessors for a second, the world can be in three basic states. There is an initial offer which has not been answered There is an offer which has been answered and no outstanding offers There is an offer which has been answered and an outstanding offer In the first two cases, there is only one localdesc, which is either answered or not. In the second case, there are two localdescs, one confirmed and one answered or not. As Justin observes, currently localdesc is the most recent description set, regardless of whether it's answered. I find his argument persuasive here. I would prefer that we have two variables: Most recent answered description Most recent non-answered description And in some cases either or both of these can be null. We can obviously keep localdescription around for a while for compat. I don't feel strongly about the names here, so I won't suggest some just yet. Let's agree on the principle one way or the other.
The world can be in four basic states, the fourth being the initial state of no offer at all, which is the only state where "Most recent answered description" would be I hope? This would fit my understanding of "most recent": while it may be initially (meaning "never been set"), it will never go to after that (which would surprise me). I think we're on the same page here. Can "Most recent non-answered description" ever go from non- to ? If it can, then lets avoid the false symmetry with the first one: Most recent answered description, or if never set. Most recent non-answered description if there is one since the last answered description, or . The first one is a.k.a. . The second one is a temporal variable: it'll only ever be non- during re-negotiation, correct? Moreover, during re-negotiation, it's indistinguishable from , do I have that right? So, counting which we have today, why add a redundant third temporal variable that all it brings to the table is that it is outside of renegotiation?
, jan-ivar EMAIL wrote: Yes, then everything is null. No. So, counting localDescription which we have today, we're adding a redundant
What's the value of "most recent non-answered description" after rollback? (matters for the question of whether it can go from non-null to null)
Right, hanging on to a failed description doesn't make much sense, so I see how we got to . So lets not cut it that way. I think a JS writer cares about: the last set value, and the reigning value. Where rollback rolls back failed set values to the known-good reigning value. Having itself be the last-set-value matches most attribute patterns I've seen. (e.g. ).
The problem with this categorization is that in the case of re-offer, there isn't "the reigning value". Rather, the offerer has two values which are simultaneously valid, so I think Justin's approach is superior. In any case, rather than debate this here, let's discuss it at the interim.
So, given what is being discussed here is about PC spec, I'd sort of like to close this and move the conversation over to PC and not jsep.
I agree this overlaps with PC, but given the relevance of this to the overall JSEP O-A model, I think we need to have some description of this in Section 4.1.*
Personal opinion (not claiming to represent any consensus): JSEP needs to describe the procedures followed to get the SDP we want. JSEP shouldn't need to talk about accessors at all; we can leave that to WEBRTC. What's specified in only one place has a greater chance of being consistent.
I find that logic persuasive, in that the accessors are not relevant to the state machine or any other fundamental part of JSEP. That would imply that 4.1.7 and 4.1.8 ought to be removed from this document, and probably also 4.1.9 (canTrickleIceCandidates, another accessor-like API). NAME wdyt?
I can live with that, but I thought that we had agreed previously that JSEP would document this stuff and place requirements on the WebRTC API. , Justin Uberti EMAIL wrote:
It's perfectly reasonable to have a sentence saying "the API will give access to current and pending SDP and whether or not trickleIce is supported". It's when we get the discussion about what the accessor names should be in 2 different places that I feel like we're not using our time optimally.
Well, I suggest we have one discussion and then put it in both places. , Harald Alvestrand <EMAIL
Consensus in W3C was to have two new accessors. This is editor ready.
Resolved by

Revised text:
application that gathering is occurring through an event.  Then, when each new ICE candidate becomes available, the ICE Agent will supply it to the application via an additional event; these candidates will  <ins> also automatically be added to the current and/or pending local session description.  Finally, when all candidates have been gathered, an event will be dispatched to signal that the gathering process is complete. </ins> Note that gathering phases only gather the candidates needed by new/recycled/restarting m= lines; other m= lines continue to use provisional answers, and any previous call leg will be terminated. At some point, the application will end the setup process, perhaps with a timer; at this point, the application could reapply the  <ins> pending remote description as a final answer. </ins> 3.6.2. this, we introduce the concept of "rollback". A rollback discards any proposed changes to the session, returning  <ins> the state machine to the stable state, and setting the pending local and/or remote description back to null.  Any resources or candidates that were allocated by the abandoned local description are discarded; any media that is received will be processed according to the previous local and remote descriptions.  Rollback can only be used to cancel proposed changes; there is no support for rolling back from a stable state to a previous stable state.  Note that this implies that once the answerer has performed setLocalDescription with his answer, this cannot be rolled back. </ins> A rollback is performed by supplying a session description of type "rollback" with empty contents to either setLocalDescription or successfully handle scenarios where the application wants to offer to change from one media format to a different, incompatible format, the PeerConnection must be able to simultaneously support use of both the  <ins> current and pending local descriptions (e.g. support codecs that exist in both descriptions) until a final answer is received, at which point the PeerConnection can fully adopt the pending local description, or roll back to the current description if the remote side denied the change. </ins> This API indirectly controls the candidate gathering process.  When a local description is supplied, and the number of transports currently description, the PeerConnection will create transports as needed and begin gathering candidates for them.  <ins> If setRemoteDescription was previously called with an offer, and </ins> setLocalDescription is called with an answer (provisional or final), and the media directions are compatible, and media are available to send, this will result in the starting of media transmission. 4.1.7.  <ins> The currentLocalDescription method returns a copy of the current negotiated local description - i.e., the local description from the last successful offer/answer exchange - in addition to any local candidates that have been generated by the ICE Agent since the local description was set. </ins>  <ins> A null object will be returned if an offer/answer exchange has not yet been completed. </ins> 4.1.8.  <ins> The pendingLocalDescription method returns a copy of the local description currently in negotiation - i.e., a local offer set without any corresponding remote answer - in addition to any local candidates that have been generated by the ICE Agent since the local description was set. </ins>  <ins> A null object will be returned if the state of the PeerConnection is "stable" or "have-remote-offer". </ins> 4.1.9. <ins> The currentRemoteDescription method returns a copy of the current negotiated remote description - i.e., the remote description from the last successful offer/answer exchange - in addition to any remote candidates that have been supplied via processIceMessage since the remote description was set. A null object will be returned if an offer/answer exchange has not yet been completed. 4.1.10. The pendingRemoteDescription method returns a copy of the remote description currently in negotiation - i.e., a remote offer set without any corresponding local answer - in addition to any remote candidates that have been supplied via processIceMessage since the remote description was set. A null object will be returned if the state of the PeerConnection is "stable" or "have-local-offer". 4.1.11. </ins> The canTrickleIceCandidates property indicates whether the remote side supports receiving trickled candidates.  There are three potential values: Trickle on initial offers and Full Trickle on subsequent interactions with a Trickle ICE-compatible agent.  <ins> 4.1.12. </ins> The setConfiguration method allows the global configuration of the PeerConnection, which was initially set by constructor parameters, to may result in a change to media state if it results in connectivity being established.  <ins> 4.1.13. </ins> The addIceCandidate method provides a remote candidate to the ICE  <ins> Agent, which, if parsed successfully, will be added to the current and/or pending remote description according to the rules defined for Trickle ICE.  Connectivity checks will be sent to the new candidate. </ins> This call will result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity