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


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

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/intro_pjsua2

    v1 v1  
     1{{{ 
     2#!rst 
     3PJSUA2-High Level API 
     4****************************** 
     5The PJSUA2 is an object-oriented abstraction above ​PJSUA API. It provides high level API for constructing ​Session Initiation Protocol (SIP) multimedia user agent applications (a.k.a Voice over IP/VoIP softphones). It wraps together the signaling, media, and NAT traversal functionality into easy to use call control API, account management, buddy list management, presence, and instant messaging, along with multimedia features such as local conferencing, file streaming, local playback, and voice recording, and powerful NAT traversal techniques utilizing ​STUN, ​TURN, and ​ICE. 
     6 
     7PJSUA2 Main Classes 
     8====================== 
     9Here are the main classes of the PJSUA2. 
     10Endpoint 
     11-------------- 
     12This is the main class of PJSUA2. You need to instantiate one and exactly one of this class, and from the instance you can then initialize and start the library. 
     13 
     14Account 
     15------------- 
     16An account specifies the identity of the person (or endpoint) on one side of SIP conversation. At least one account instance needs to be created before anything else, and from the account instance you can start making/receiving calls as well as adding buddies. 
     17 
     18Media 
     19---------- 
     20This class represents a media element which is capable to either produce media or takes media. 
     21 
     22Call 
     23------ 
     24This class is used to manipulate calls, such as to answer the call, hangup the call, put the call on hold, transfer the call, etc. 
     25 
     26Buddy 
     27--------- 
     28This class represents a remote buddy (a person, or a SIP endpoint). You can subscribe to presence status of a buddy to know whether the buddy is online/offline/etc., and you can send and receive instant messages to/from the buddy. 
     29 
     30General Concepts 
     31================== 
     32Class Usage Patterns 
     33--------------------- 
     34With 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. 
     35 
     36Objects Persistence 
     37--------------------- 
     38PJSUA2 includes PersistentObject class to provide functionality to read/write data from/to a document (string or file). The data can be simple data types such as boolean, number, string, and string arrays, or a user defined object. Currently the implementation supports reading and writing from/to JSON document, but the framework allows application to extend the API to support other document formats. 
     39 
     40As such, classes which inherit from PersistentObject, such as EpConfig (endpoint configuration), AccountConfig (account configuration), and BuddyConfig (buddy configuration) can be loaded/saved from/to a file. Here’s an example to save a config to a file:: 
     41 
     42    EpConfig epCfg; 
     43    JsonDocument jDoc; 
     44    epCfg.uaConfig.maxCalls = 61; 
     45    epCfg.uaConfig.userAgent = "Just JSON Test"; 
     46    jDoc.writeObject(epCfg); 
     47    jDoc.saveFile(“jsontest.js”); 
     48 
     49To load from the file:: 
     50 
     51    EpConfig epCfg; 
     52    JsonDocument jDoc; 
     53    jDoc.loadFile(“jsontest.js”); 
     54    jDoc.readObject(epCfg); 
     55 
     56Error Handling 
     57--------------- 
     58We 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. 
     59 
     60Asynchronous Operations 
     61------------------------- 
     62If 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. 
     63 
     64Take 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. 
     65 
     66Threading 
     67---------- 
     68For 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 should be thread safe. 
     69 
     70}}}