Changes between Version 10 and Version 11 of 3rd_Party_Media


Ignore:
Timestamp:
Mar 19, 2008 8:48:04 AM (12 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • 3rd_Party_Media

    v10 v11  
    2929 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). 
    3030 
    31  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. 
     31 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. 
    3232 
    3333  ''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).'' 
     
    4848=== Creating a Call/Invite Session === 
    4949 
    50 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. 
    51  
    52   ''[*] 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.'' 
    53  
    54 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. 
     50An [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. 
     51 
     52  ''[*] 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).'' 
     53 
     54Below 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. 
    5555 
    5656{{{ 
     
    6969    media_sock_info = pjmedia_transport_get_info(media_transport); 
    7070    
     71    // Create local and initial SDP. 
    7172    // The easiest way to create SDP is to ask the media endpoint 
    7273    // to create an SDP describing local media capability for us. 
    73     // The function needs the media socket address which will be 
    74     // placed in SDP c= and m= line. 
    7574    sdp = pjmedia_endpt_create_sdp(media_sock_info); 
    7675 
     
    114113 * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP__NEG.htm SDP Negotiator] object 
    115114 * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SDP.htm SDP representation and parsing] 
    116  
     115 * 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. 
     116 * [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. 
    117117 
    118118 
    119119=== Starting the Media === 
    120120 
    121 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. 
    122  
    123 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. 
    124  
    125 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. 
     121As 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). 
     122 
     123The [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). 
     124 
     125Below 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. 
    126126 
    127127{{{ 
     
    151151}}} 
    152152 
    153 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. 
     153And 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]. 
    154154 
    155155 
     
    184184   stream_port = pjmedia_session_get_port(m_session, 0); 
    185185 
    186    // "Connect" the audio stream to sound device (or conference bridge, 
    187    // or anything else). 
     186   // Do something with the audio stream. Here we connect it to the sound 
     187   // device. 
    188188   pjmedia_snd_port_connect(sound_device, stream_port); 
    189189} 
     
    192192For further reference, please see: 
    193193 * [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SES.htm Media session] object 
    194  * [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SND__PORT.htm Sound device port] object 
    195  * [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__PORT__CONCEPT.htm Media port framework] in PJMEDIA 
     194 * [http://www.pjsip.org/pjsip/docs/html/page_pjsip_sample_simple_ua_c.htm simpleua sample application] 
     195 * [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. 
    196196 
    197197 
     
    199199 
    200200The invite session provides additional callbacks related to SDP offer/answer negotiation: 
    201  * '''on_rx_offer()''': this callback is called when the session has received a new offer from remote, and it needs a local SDP. 
     201 * '''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). 
    202202 * '''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). 
    203203 
     
    210210=== Call Disconnection === 
    211211 
    212 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. 
     212Call 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. 
    213213 
    214214---- 
     
    216216== Third Party Media Library Integration Strategy == 
    217217 
    218 We have three approaches on how to integrate your third party media stack with PJSIP: 
     218We have three approaches on how to integrate third party media stack with PJSIP: 
    219219 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). 
    220220 1. above, plus to reuse PJMEDIA's session info generation to avoid working with SDP directly. 
     
    244244 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! 
    245245  {{{ 
    246 #!c 
     246   #!c 
    247247   #include <pjmedia/errno.h> 
    248248