Changes between Version 6 and Version 7 of 0.9/Media_Interface_Change

Timestamp:

Jun 17, 2008 3:17:35 PM (16 years ago)

Author:

bennylp

Comment:

--

0.9/Media_Interface_Change

@@ -44 +44 @@
 = New =
 
-''New code in italics''.
+''New code in italics''. ~~Deleted code is in strike-through~~.
 
 == pjsua_call.c ==
-Currently this is how the media channel interacts with SIP call in PJSUA-LIB.
+This is the proposed interaction:
 
  '''pjsua_call_make_call()''' : ::
@@ -105 +105 @@
   '''New:''' {{{encode_sdp()}}}::
    1. This function is used to modify local SDP with transport info. It can be called for different purposes below.
-   1. '''generating initial offer''': this happens for outgoing calls, right after {{{media_create()}}} is called. The transport must initialize local SDP with default values (for ICE: include all candidates. For SRTP: include all crypto options). Normally it does not need to modify it's state.
-   1. '''generating initial answer''': this happens for incoming calls, also right after {{{media_create()}}} is called. The transport must inspect the remote SDP '''and'''' update the transport according to the info in remote SDP '''and''' update local SDP to be sent as answer. For example: disable the feature if remote SDP doesn't contain the required attributes.
-   1. '''generating subsequent offer''': this happens when local endpoint sends UPDATE or re-INVITE. In this case, the transport '''MUST NOT''' modify it's state, and rather just encode it's current state in the local SDP.
-   1. '''generating subsequent answer''': this happens when we receive UPDATE or re-INVITE. The processing is similar to ''generating initial answer'' above.
 
  {{{media_start()}}}::
   1. The syntax has changed:
      - the local SDP is now ''const''. This is because it's useless to modify the local SDP there since the SDP has already been negotiated.
+
+
+== Sample: ICE processing with the new media framework ==
+
+=== Generating initial offer ===
+
+This happens in {{{encode_sdp()}}}, when ICE is not running and {{{rem_sdp==NULL}}. The transport will include all ICE candidates in the offer.
+
+=== Generating initial answer ===
+
+First, the transport detects whether the remote offer contains ICE in {{{media_create()}}}. If yes, it marks {{{use_ice=True}}}.
+
+Then in {{{encode_sdp()}}}, it checks if ICE is already running. Since this is an initial answer, ICE is not running yet. So it puts all candidates in the answer. In this function, the transport also checks for ICE-mismatch.
+
+=== Generating subsequent offer ===
+
+This happens in {{{encode_sdp()}}}, when ICE is already running and {{{rem_sdp==NULL}}}. The transport fills in the SDP with selected candidate only, one for each component.
+
+=== Generating subsequent answer ===
+
+This happens in {{{encode_sdp()}}}, when ICE is already running and {{{rem_sdp}}} is present. The transport detects for ICE '''restart''' condition or if the new offer no longer contains support for ICE. If ICE is restarted, then the internal ICE session will be destroyed and re-created.
+
+The populated SDP depends on whether ICE is restarted or not. If ICE doesn't restart, then the answer contains only the selected candidate from the valid pairs, just like ''Generating subsequent offer'' above. If ICE is restarted, then it will contains all candidates.
+
+=== media_start() processing ===
+
+When we send offer, this is where we will see the remote answer for the first time. So we do the "heavy" negotiation here.
+
+For ICE:
+ - Detect if answer contains ICE support ==> disable ICE
+ - Handle answer that contains ice-mismatch attribute ==> disable ICE
+ - Handle answer with transport address that doesn't match any candidates ==> disable ICE
+ - Handle when we set our role as Controlled, but answer contains ice-list ==> change role to Controlling
+ - If remote SDP contains the same ice-ufrag and ice-pwd as previous SDP, that means there's no change in the offer/answer, no need to do anything.
+
+If things are okay, start ICE negotiation.