Changes between Version 7 and Version 8 of pjsip-doc/intro_pjsua2


Ignore:
Timestamp:
Feb 6, 2014 9:22:37 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/intro_pjsua2

    v7 v8  
    3838With the methods of the main classes above, you will be able to invoke various operations to the object quite easily. But how can we get events/notifications from these classes? Each of the main classes above (except Media) will get their events in the callback methods. So to handle these events, just derive a class from the corresponding class (​Endpoint, Call, Account, or Buddy) and implement/override the relevant method (depending on which event you want to handle). More will be explained in later sections. 
    3939 
     40Error Handling 
     41--------------- 
     42We use exceptions as means to report error, as this would make the program flows more naturally. Operations which yield error will raise ​Error exception. If you prefer to display the error in more structured manner, the ​Error class has several members to explain the error, such as the operation name that raised the error, the error code, and the error message itself. 
     43 
     44Asynchronous Operations 
     45------------------------- 
     46If you have developed applications with PJSIP, you'll know about this already. In PJSIP, all operations that involve sending and receiving SIP messages are asynchronous, meaning that the function that invokes the operation will complete immediately, and you will be given the completion status as callbacks. 
     47 
     48Take a look for example the ​makeCall() method of the Call class. This function is used to initiate outgoing call to a destination. When this function returns successfully, it does not mean that the call has been established, but rather it means that the call has been initiated successfully. You will be given the report of the call progress and/or completion in the ​onCallState() callback method of ​Call class. 
     49 
     50Threading 
     51---------- 
     52For platforms that require polling, the PJSUA2 module provides its own worker thread to poll PJSIP, so it is not necessary to instantiate own your polling thread. Having said that the application should be prepared to have the callbacks called by different thread than the main thread. The PJSUA2 module itself is thread safe. 
     53 
     54Problem with Garbage Collection 
     55------------------------------- 
     56Garbage collection (GC) exists in Java and Python (and other languages, but we don't support those for now), and there are some problems with it when it comes to PJSUA2 usage: 
     57 
     58- it delays the destruction of objects (including PJSUA2 objects), causing the code in object's destructor to be executed out of order 
     59- the GC operation may run on different thread not previously registered to PJLIB, causing assertion 
     60 
     61Due to problems above, application '''MUST immediately destroy PJSUA2 objects using object's delete() method (in Java)''', instead of relying on the GC to clean up the object. 
     62 
     63For example, to delete an Account, it's '''NOT''' enough to just let it go out of scope. Application MUST delete it manually like this (in Java): 
     64 
     65.. code-block:: c++ 
     66 
     67    acc.delete(); 
     68 
     69 
     70 
     71 
    4072Objects Persistence 
    4173--------------------- 
     
    6193    jDoc.loadFile("jsontest.js"); 
    6294    jDoc.readObject(epCfg); 
    63  
    64 Error Handling 
    65 --------------- 
    66 We use exceptions as means to report error, as this would make the program flows more naturally. Operations which yield error will raise ​Error exception. If you prefer to display the error in more structured manner, the ​Error class has several members to explain the error, such as the operation name that raised the error, the error code, and the error message itself. 
    67  
    68 Asynchronous Operations 
    69 ------------------------- 
    70 If you have developed applications with PJSIP, you'll know about this already. In PJSIP, all operations that involve sending and receiving SIP messages are asynchronous, meaning that the function that invokes the operation will complete immediately, and you will be given the completion status as callbacks. 
    71  
    72 Take a look for example the ​makeCall() method of the Call class. This function is used to initiate outgoing call to a destination. When this function returns successfully, it does not mean that the call has been established, but rather it means that the call has been initiated successfully. You will be given the report of the call progress and/or completion in the ​onCallState() callback method of ​Call class. 
    73  
    74 Threading 
    75 ---------- 
    76 For platforms that require polling, the PJSUA2 module provides its own worker thread to poll PJSIP, so it is not necessary to instantiate own your polling thread. Having said that the application should be prepared to have the callbacks called by different thread than the main thread. The PJSUA2 module itself is thread safe. 
    7795 
    7896