Changes between Version 10 and Version 11 of 3rd_Party_Media

Timestamp:

Mar 19, 2008 8:48:04 AM (16 years ago)

Author:

bennylp

Comment:

--

3rd_Party_Media

@@ -29 +29 @@
  The media stack includes [http://www.pjsip.org/pjmedia/docs/html/index.htm PJMEDIA and PJMEDIA-CODEC]. Depending on the library packaging, it may contain '''SDP components''' (message representation, parsing, and SDP offer answer negotiation).
 
- Although the SDP components ([http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP.htm message representation, parsing], and SDP [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm offer answer negotiation]) may be packaged with PJMEDIA, actually it is independent from PJMEDIA and it can be (and has been) used independently from PJMEDIA. This is because although media can be optional for some application (for example, a server), SDP and SDP negotiation are needed by the invite session, so it should be able to use these parts without having to use PJMEDIA.
+ Although the SDP components ([http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP.htm message representation, parsing], and SDP [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm offer answer negotiation]) may be packaged with PJMEDIA, actually it is independent from PJMEDIA and it can be (and has been) used independently from PJMEDIA. This is because although media can be optional for some application (for example, a server), SDP and SDP negotiation are needed by and tightly coupled to the [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm invite session] (sip_inv.c), so it should be able to use these parts without having to use PJMEDIA.
 
   ''Note: in Symbian build system, these SDP parts are packaged on separate static library (as '''PJSDP''' library) and removed from PJMEDIA. On GNU build system, both PJMEDIA and PJSDP libraries are built, but the SDP parts are included in PJMEDIA as well, so only PJMEDIA is needed to be linked with the application (since the PJMEDIA library here also contains PJSDP parts).''
@@ -48 +48 @@
 === Creating a Call/Invite Session ===
 
-An [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm invite session] is created by application (or PJSUA-LIB) when we make outgoing call or when we receive incoming call. We need to specify our local SDP when creating the invite session, because SDP negotiation will be done by the invite session [*], and to do this it needs SDP from both local and remote endpoints.
-
-  ''[*] To be precise, the negotiation actually is done by the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP negotiator] (part of PJMEDIA/PJSDP library) which will be invoked by the invite session. The motivation to make SDP negotiation as integral part of invite session is to shield application from the complexity of SDP offer/answer session (for example, with late offer/answer, offer/answer quirks related to the use of PRACK, and ability to update session early with UPDATE), while maintaining the flexibility for the application to control when and what offer and answer to be given to remote.''
-
-Below is the pseudo-code for creating a call/invite session. The procedure is relatively similar for both caller and callee. For a working sample, please see [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm '''simpleua''' sample] or PJSUA-LIB source code.
+An [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm invite session] is created by application (or PJSUA-LIB) when we make or receive calls. We need to specify our local SDP when creating the invite session, because SDP negotiation will be done by the invite session [*], and to do this it needs SDP from both local and remote endpoints.
+
+  ''[*] To be precise, the negotiation actually is done by the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP negotiator] (part of PJMEDIA/PJSDP library) which will be invoked by the invite session. The motivation to make SDP negotiation as integral part of invite session is to shield application from the complexity of SDP offer/answer session (for example, with late offer/answer, offer/answer quirks related to the use of PRACK, and ability to update session early with UPDATE), while maintaining the flexibility for the application to control when and what offer and answer to be given to remote. Also an invite session always negotiate SDP, regardless whether the application is a user agent or a back to back user agent (and indeed people have used pjsip to build B2BUA).''
+
+Below is the pseudo-code for creating a call/invite session. The procedure is relatively similar for both caller and callee. For a working sample, please see the [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample application] or PJSUA-LIB source code.
 
 {{{
@@ -69 +69 @@
     media_sock_info = pjmedia_transport_get_info(media_transport);
    
+    // Create local and initial SDP.
     // The easiest way to create SDP is to ask the media endpoint
     // to create an SDP describing local media capability for us.
-    // The function needs the media socket address which will be
-    // placed in SDP c= and m= line.
     sdp = pjmedia_endpt_create_sdp(media_sock_info);
 
@@ -114 +113 @@
  * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP Negotiator] object
  * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP.htm SDP representation and parsing]
-
+ * the PJSIP Developer's Guide PDF (available from [http://www.pjsip.org/docs.htm]) contains details information on the interaction between the invite session and SDP negotiator.
+ * [http://www.pjsip.org/pjsip/docs/html/page_pjmedia_samples_siprtp_c.htm siprtp sample application] is a sample application that sends/receives RTP packets without using stream.
 
 
 === Starting the Media ===
 
-As discussed above, SDP negotiation is done by the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP negotiator] object that is invoked internally by [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm the invite session]. The invite session user (application or PJSUA-LIB) will get notification whenever the SDP negotiation has been done, via invite session's '''on_media_update()''' callback.
-
-The [http://www.pjsip.org/pjsip/docs/html/structpjsip__inv__callback.htm#aafbe25fa41f5aa57dfe5a42bf025f2d on_media_update()] callback contains ''status'' parameter which tells application whether SDP negotiation has been successful (or not). We are normally only interested with the successful status to start our media.
-
-Below is the pseudo-code to implement ''on_media_update()'' callback. You can see a working implementation of this function in [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample] or ''pjsua_call_on_media_update()'' function of {{{pjsua_call.c}}} in PJSUA-LIB.
+As discussed above, SDP negotiation is done by the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP negotiator] object that is invoked internally by [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__INV.htm the invite session]. When SDP negotiation has been completed, the invite application (or PJSUA-LIB) will get notification via invite session's '''on_media_update()''' callback. SDP negotiation is marked as completed as soon as an offer is answered (either in 200/OK response to INVITE, in 18x response, 200/OK response to UPDATE, or in PRACK exchange).
+
+The [http://www.pjsip.org/pjsip/docs/html/structpjsip__inv__callback.htm#aafbe25fa41f5aa57dfe5a42bf025f2d on_media_update()] callback contains ''status'' parameter which tells application whether SDP negotiation has been successful (or not). We are normally only interested with the successful status to start our media. Failure status will be handled by the invite session (e.g. to send failure response to remote).
+
+Below is the pseudo-code to implement ''on_media_update()'' callback. You can see a working implementation of this function in the [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample] or ''pjsua_call_on_media_update()'' function of {{{pjsua_call.c}}} in PJSUA-LIB.
 
 {{{
@@ -151 +151 @@
 }}}
 
-And below is the pseudo-code of ''update_media_channel()'' function. You can see a working implementation of this function in ''pjsua_media_channel_update()'' of pjsua_media.c in PJSUA-LIB.
+And below is the pseudo-code of ''update_media_channel()'' function. You can see a working implementation of this function in ''pjsua_media_channel_update()'' of pjsua_media.c in PJSUA-LIB or in [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample application].
 
 
@@ -184 +184 @@
    stream_port = pjmedia_session_get_port(m_session, 0);
 
-   // "Connect" the audio stream to sound device (or conference bridge,
-   // or anything else).
+   // Do something with the audio stream. Here we connect it to the sound
+   // device.
    pjmedia_snd_port_connect(sound_device, stream_port);
 }
@@ -192 +192 @@
 For further reference, please see:
  * [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SES.htm Media session] object
- * [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SND__PORT.htm Sound device port] object
- * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__PORT__CONCEPT.htm Media port framework] in PJMEDIA
+ * [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample application]
+ * [http://www.pjsip.org/pjsip/docs/html/page_pjmedia_samples_siprtp_c.htm siprtp sample application] is a sample application that sends/receives RTP packets without using stream.
 
 
@@ -199 +199 @@
 
 The invite session provides additional callbacks related to SDP offer/answer negotiation:
- * '''on_rx_offer()''': this callback is called when the session has received a new offer from remote, and it needs a local SDP.
+ * '''on_rx_offer()''': this callback is called when the session has received a new offer from remote, and it needs a local SDP to be negotiated as SDP answer (by calling ''pjsip_inv_set_sdp_answer()'' with the SDP).
  * '''on_create_offer()''': this callback is called when the session needs to generate a local offer (for example when it receives incoming re-INVITE without an offer).
 
@@ -210 +210 @@
 === Call Disconnection ===
 
-Call disconnection occurs when the invite session calls ''on_state_changed()'' of [http://www.pjsip.org/pjsip/docs/html/structpjsip__inv__callback.htm pjsip_inv_callback] with invite session state equal to ''PJSIP_INV_STATE_DISCONNECTED''. Application should release the media resources allocated for the call on this event.
+Call disconnection occurs when the invite session calls ''on_state_changed()'' callback of [http://www.pjsip.org/pjsip/docs/html/structpjsip__inv__callback.htm pjsip_inv_callback] with invite session state equal to ''PJSIP_INV_STATE_DISCONNECTED''. Application should release the media resources allocated for the call on this event.
 
 ----
@@ -216 +216 @@
 == Third Party Media Library Integration Strategy ==
 
-We have three approaches on how to integrate your third party media stack with PJSIP:
+We have three approaches on how to integrate third party media stack with PJSIP:
  1. to only use SDP components of PJMEDIA and nothing else (the SDP messaging, parsing, and offer answer negotiation are still needed since they are tightly coupled with the invite session for the reasons explained above).
  1. above, plus to reuse PJMEDIA's session info generation to avoid working with SDP directly.
@@ -244 +244 @@
  1. Register PJMEDIA's specific error code to PJLIB error code space, using the code snippet below. This normally is done when we call ''pjmedia_endpt_create()'', but we can't call this function since we are not using PJMEDIA of course!
   {{{
-#!c
+   #!c
    #include <pjmedia/errno.h>