Changes between Initial Version and Version 1 of pjsip-doc/endpoint


Ignore:
Timestamp:
Dec 4, 2013 1:45:48 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/endpoint

    v1 v1  
     1{{{ 
     2#!rst 
     3 
     4Endpoint 
     5************ 
     6The ​Endpoint class is a singleton class, and application MUST create one and at most one of this class instance before it can do anything else. This class is the core class of PJSUA2, and it provides the following functions: 
     7 
     8- Starting up and shutting down 
     9- Customization of configurations, such as core UA (User Agent) SIP configuration, media configuration, and logging configuration 
     10 
     11This section will describe the functions above. 
     12 
     13To use the Endpoint class, application DOES NOT need to subclass it unless: 
     14 
     15- application wants to implement/override Endpoint’s callback methods to get the events such as transport state change or NAT detection completion, or 
     16- application schedules a timer using Endpoint.utilTimerSchedule() API. In this case, application needs to implement the onTimer() callback to get the notification when the timer expires. 
     17 
     18Instantiating the Endpoint 
     19-------------------------- 
     20Before anything else, you must instantiate the Endpoint class:: 
     21 
     22    Endpoint *ep = new Endpoint; 
     23 
     24Once the endpoint is instantiated, you can retrieve the Endpoint instance using Endpoint.instance() static method. 
     25 
     26Creating the Library 
     27---------------------- 
     28Create the library by calling its libCreate() method:: 
     29 
     30    try { 
     31        ep->libCreate(); 
     32    } catch(Error& err) { 
     33        cout << "Startup error: " << err.reason << endl; 
     34    } 
     35 
     36The libCreate() method will raise exception if error occurs, so we need to trap the exception using try/catch clause as above. 
     37 
     38Initializing the Library and Configuring the Settings 
     39---------------------------------------------------------------------------- 
     40The EpConfig class provides endpoint configuration which allows the customization of the following settings: 
     41 
     42​- UAConfig, to specify core SIP user agent settings. 
     43​- MediaConfig, to specify various media settings, including ICE and TURN. 
     44​- LogConfig, to customize logging settings. 
     45 
     46To customize the settings, create instance of EpConfig class and specify them during the endpoint initialization (will be explained more later), for example:: 
     47 
     48    EpConfig ep_cfg; 
     49    ep_cfg.logConfig.level = 5; 
     50    ep_cfg.uaConfig.maxCalls = 4; 
     51    ep_cfg.mediaConfig.sndClockRate = 16000; 
     52 
     53Next, you can initialize the library by calling libInit():: 
     54 
     55    try { 
     56        EpConfig ep_cfg; 
     57        // Specify customization of settings in ep_cfg 
     58        ep->libInit(ep_cfg); 
     59    } catch(Error& err) { 
     60        cout << "Initialization error: " << err.reason << endl; 
     61    } 
     62 
     63The snippet above initializes the library with the default settings. 
     64 
     65Creating One or More Transports 
     66-------------------------------------------------- 
     67Application needs to create one or more ​transports before it can send or receive SIP messages:: 
     68 
     69    try { 
     70        TransportConfig tcfg; 
     71        tcfg.port = 5060; 
     72        TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_UDP, tcfg); 
     73    } catch(Error& err) { 
     74        cout << "Transport creation error: " << err.reason << endl; 
     75    } 
     76 
     77The transportCreate() method returns the newly created ​Transport ID and it takes the transport type and ​TransportConfig object to customize the transport settings like bound address and listening port number. Without this, by default the transport will be bound to INADDR_ANY and any available port. 
     78 
     79There is no real use of the ​Transport ID, except to create userless account (with ​Account.create(), as will be explained later), and perhaps to display the list of transports to user if the application wants it. 
     80 
     81Starting the Library 
     82-------------------- 
     83Now we're ready to start the library. We need to start the library to finalize the initialization phase, e.g. to complete the initial STUN address resolution, initialize/start the sound device, etc. To start the library, call ​libStart() method:: 
     84 
     85    try { 
     86        ep->libStart(); 
     87    } catch(Error& err) { 
     88        cout << "Startup error: " << err.reason << endl; 
     89    } 
     90 
     91Shutting Down the Library 
     92-------------------------------------- 
     93Once the application exits, the library needs to be shutdown so that resources can be released back to the operating system. This is done by deleting the Endpoint instance, which will internally call ​libDestroy():: 
     94 
     95    delete ep; 
     96 
     97}}}