Changes between Version 12 and Version 13 of pjsip-doc/intro_pjsua2


Ignore:
Timestamp:
Feb 26, 2014 6:45:18 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/intro_pjsua2

    v12 v13  
    77PJSUA2 is implemented on top of PJSUA-LIB API. The SIP and media features and object modelling follows what PJSUA-LIB provides (for example, we still have accounts, call, buddy, and so on), but the API to access them is different. These features will be described later in this chapter. PJSUA2 is a C++ library, which you can find under ``pjsip`` directory in the PJSIP distribution. The C++ library can be used by native C++ applications directly. But PJSUA2 is not just a C++ library. From the beginning, it has been designed to be accessible from high level non-native languages such as Java and Python. This is achieved by SWIG binding. And thanks to SWIG, binding to other languages can be added relatively easily in the future. 
    88 
    9  
    10 Building PJSUA2 
    11 ====================== 
    12 The PJSUA2 C++ library will be built by default by PJSIP build system. 
    13  
    14 The SWIG modules for Python and Java are built by invoking ``make`` manually from ``pjsip-apps/src/swig`` directory. 
    159 
    1610 
     
    10296 
    10397 
     98Building PJSUA2 
     99====================== 
     100The PJSUA2 C++ library will be built by default by PJSIP build system. 
     101 
     102Building Python and Java SWIG Modules 
     103====================================== 
     104The SWIG modules for Python and Java are built by invoking ``make`` and ``make install`` manually from ``pjsip-apps/src/swig`` directory. The ``make install`` will install the Python SWIG module to user's ``site-packages`` directory. 
     105 
     106Requirements 
     107------------ 
     108 
     109#. ``JDK``. 
     110#. ``Python``, version 2.7 or above is required. 
     111   For **Linux/UNIX**, you will also need ``Python developent package`` (called ``python-devel`` (e.g. on Fedora) or ``python2.7-dev`` (e.g. on Ubuntu)). For **Windows**, you will need MinGW and ``Python SDK`` such as `ActivePython-2.7.5`_ from `ActiveState`_. 
     112 
     113.. _`ActivePython-2.7.5`: http://www.activestate.com/activepython/downloads 
     114.. _`ActiveState`: http://www.activestate.com 
     115 
     116Testing The Installation 
     117------------------------ 
     118To test the installation, simply run python and import ``pjsua2`` module:: 
     119 
     120  $ python 
     121  > import pjsua2 
     122  > ^Z 
     123 
     124 
     125Using in C++ Application 
     126======================== 
     127As mentioned in previous chapter, a C++ application can use *pjsua2* natively, while at the same time still has access to the lower level objects and the ability to extend the libraries if it needs to. Using the API will be exactly the same as the API reference that is written in this book. 
     128 
     129Here is a sample complete C++ application to give you some idea about the API. The snippet below initializes the library and creates an account that registers to our pjsip.org SIP server. 
     130 
     131.. code-block:: c++ 
     132     
     133  #include <pjsua2.hpp> 
     134  #include <iostream> 
     135   
     136  using namespace pj; 
     137   
     138  // Subclass to extend the Account and get notifications etc. 
     139  class MyAccount : public Account { 
     140  public: 
     141      virtual void onRegState(OnRegStateParam &prm) { 
     142          AccountInfo ai = getInfo(); 
     143          std::cout << (ai.regIsActive? "*** Register:" : "*** Unregister:") 
     144                    << " code=" << prm.code << std::endl; 
     145      } 
     146  }; 
     147 
     148  int main() 
     149  { 
     150      Endpoint ep; 
     151       
     152      ep.libCreate(); 
     153       
     154      // Initialize endpoint 
     155      EpConfig ep_cfg; 
     156      ep.libInit( ep_cfg ); 
     157       
     158      // Create SIP transport. Error handling sample is shown 
     159      TransportConfig tcfg; 
     160      tcfg.port = 5060; 
     161      try { 
     162          ep.transportCreate(PJSIP_TRANSPORT_UDP, tcfg); 
     163      } catch (Error &err) { 
     164          std::cout << err.info() << std::endl; 
     165          return 1; 
     166      } 
     167       
     168      // Start the library (worker threads etc) 
     169      ep.libStart(); 
     170      std::cout << "*** PJSUA2 STARTED ***" << std::endl; 
     171       
     172      // Configure an AccountConfig 
     173      AccountConfig acfg; 
     174      acfg.idUri = "sip:test@pjsip.org"; 
     175      acfg.regConfig.registrarUri = "sip:pjsip.org"; 
     176      AuthCredInfo cred("digest", "*", "test", 0, "secret"); 
     177      acfg.sipConfig.authCreds.push_back( cred ); 
     178       
     179      // Create the account 
     180      MyAccount *acc = new MyAccount; 
     181      acc->create(acfg); 
     182       
     183      // Here we don't have anything else to do.. 
     184      pj_thread_sleep(10000); 
     185       
     186      // Delete the account. This will unregister from server 
     187      delete acc; 
     188       
     189      // This will implicitly shutdown the library 
     190      return 0; 
     191  } 
     192 
     193 
     194Using in Python Application 
     195=========================== 
     196The equivalence of the C++ sample code above in Python is as follows: 
     197 
     198.. code-block:: python 
     199 
     200  # Subclass to extend the Account and get notifications etc. 
     201  class Account(pj.Account): 
     202    def onRegState(self, prm): 
     203        print "***OnRegState: " + prm.reason 
     204 
     205  # pjsua2 test function 
     206  def pjsua2_test(): 
     207    # Create and initialize the library 
     208    ep_cfg = pj.EpConfig() 
     209    ep = pj.Endpoint() 
     210    ep.libCreate() 
     211    ep.libInit(ep_cfg) 
     212     
     213    # Create SIP transport. Error handling sample is shown 
     214    sipTpConfig = pj.TransportConfig(); 
     215    sipTpConfig.port = 5060; 
     216    ep.transportCreate(pj.PJSIP_TRANSPORT_UDP, sipTpConfig); 
     217    # Start the library 
     218    ep.libStart(); 
     219     
     220    acfg = pj.AccountConfig(); 
     221    acfg.idUri = "sip:test@pjsip.org"; 
     222    acfg.regConfig.registrarUri = "sip:pjsip.org"; 
     223    cred = pj.AuthCredInfo("digest", "*", "test", 0, "pwtest"); 
     224    acfg.sipConfig.authCreds.append( cred ); 
     225    # Create the account 
     226    acc = Account(); 
     227    acc.create(acfg); 
     228    # Here we don't have anything else to do.. 
     229    time.sleep(10); 
     230 
     231    # Destroy the library 
     232    ep.libDestroy() 
     233 
     234  # 
     235  # main() 
     236  # 
     237  if __name__ == "__main__": 
     238    pjsua2_test() 
     239 
     240 
     241Using in Java Application 
     242========================= 
     243The equivalence of the C++ sample code above in Java is as follows: 
     244 
     245.. code-block:: java 
     246 
     247  import org.pjsip.pjsua2.*; 
     248 
     249  // Subclass to extend the Account and get notifications etc. 
     250  class MyAccount extends Account { 
     251    @Override 
     252    public void onRegState(OnRegStateParam prm) { 
     253        System.out.println("*** On registration state: " + prm.getCode() + prm.getReason()); 
     254    } 
     255  } 
     256 
     257  public class test { 
     258    static { 
     259        System.loadLibrary("pjsua2"); 
     260        System.out.println("Library loaded"); 
     261    } 
     262     
     263    public static void main(String argv[]) { 
     264        try { 
     265            // Create endpoint 
     266            Endpoint ep = new Endpoint(); 
     267            ep.libCreate(); 
     268            // Initialize endpoint 
     269            EpConfig epConfig = new EpConfig(); 
     270            ep.libInit( epConfig ); 
     271            // Create SIP transport. Error handling sample is shown 
     272            TransportConfig sipTpConfig = new TransportConfig(); 
     273            sipTpConfig.setPort(5060); 
     274            ep.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_UDP, sipTpConfig); 
     275            // Start the library 
     276            ep.libStart(); 
     277 
     278            AccountConfig acfg = new AccountConfig(); 
     279            acfg.setIdUri("sip:test@pjsip.org"); 
     280            acfg.getRegConfig().setRegistrarUri("sip:pjsip.org"); 
     281            AuthCredInfo cred = new AuthCredInfo("digest", "*", "test", 0, "secret"); 
     282            acfg.getSipConfig().getAuthCreds().add( cred ); 
     283            // Create the account 
     284            MyAccount acc = new MyAccount(); 
     285            acc.create(acfg); 
     286            // Here we don't have anything else to do.. 
     287            Thread.sleep(10000); 
     288            /* Explicitly delete the account. 
     289             * This is to avoid GC to delete the endpoint first before deleting 
     290             * the account. 
     291             */ 
     292            acc.delete(); 
     293             
     294            // Explicitly destroy and delete endpoint 
     295            ep.libDestroy(); 
     296            ep.delete(); 
     297             
     298        } catch (Exception e) { 
     299            System.out.println(e); 
     300            return; 
     301        } 
     302    } 
     303  } 
    104304}}}