Changeset 4762 for pjproject

Timestamp:

Feb 24, 2014 11:00:15 AM (11 years ago)

Author:

bennylp

Message:

More re #1715: doxygen integration into the book

Location:

pjproject/trunk/doc/pjsip-book

Files:

• . (modified) (1 prop)
• Doxyfile (modified) (1 diff)
• Makefile (modified) (1 diff)
• _build (modified) (1 prop)
• account.rst (modified) (5 diffs)
• call.rst (modified) (6 diffs)
• consider.rst (modified) (1 diff)
• endpoint.rst (modified) (7 diffs)
• fetch_trac.py (modified) (3 diffs)
• getting_started.rst (added)
• index.rst (modified) (3 diffs)
• intro.rst (modified) (2 diffs)
• intro_pjsua2.rst (modified) (5 diffs)
• media.rst (modified) (4 diffs)
• media_quality.rst (modified) (2 diffs)
• network_problems.rst (modified) (2 diffs)
• optimization.rst (modified) (2 diffs)
• presence.rst (modified) (1 diff)
• reference.rst (modified) (1 diff)
• samples.rst (modified) (2 diffs)

pjproject/trunk/doc/pjsip-book/Doxyfile

@@ -649 +649 @@
 # with spaces.
 
-INPUT                  = ../../pjsip/include/pjsua2/media.hpp
+INPUT                  = ../../pjsip/include/pjsua2
 
 # This tag can be used to specify the character encoding of the source files

pjproject/trunk/doc/pjsip-book/Makefile

@@ -46 +46 @@
         -rm -rf html
 
-xml:    Doxyfile
+xml:    Doxyfile ../../pjsip/include/pjsua2
         doxygen
 

pjproject/trunk/doc/pjsip-book/account.rst

@@ -1 @@
-
 
 Accounts
 =========
-​Accounts provide identity (or identities) of the user who is currently using the application. An account has one SIP Uniform Resource Identifier (URI) associated with it. In SIP terms, the identity is used as the From header in outgoing requests.
-
-Account may or may not have client registration associated with it. An account is also associated with route set and some authentication credentials, which are used when sending SIP request messages using the account. An account also has presence online status, which will be reported to remote peer when they subscribe to the account's presence, or which is published to a presence server if presence publication is enabled for the account.
+Accounts provide identity (or identities) of the user who is currently using the application. An account has one SIP Uniform Resource Identifier (URI) associated with it. In SIP terms, this URI acts as Address of Record (AOR) of the person and is used as the From header in outgoing requests.
+
+Account may or may not have client registration associated with it. An account is also associated with route set and some authentication credentials, which are used when sending SIP request messages using the account. An account also has presence status, which will be reported to remote peer when they subscribe to the account's presence, or which is published to a presence server if presence publication is enabled for the account.
 
 At least one account MUST be created in the application, since any outgoing requests require an account context. If no user association is required, application can create a userless account by calling Account.create(). A userless account identifies local endpoint instead of a particular user, and it corresponds to a particular transport ID.
 
-Also one account must be set as the default account, which will be used as the account identity when pjsua fails to match the request with any accounts using the stricter matching rules.
+Also one account must be set as the default account, which will be used as the account identity when pjsua fails to match incoming request with any accounts using the stricter matching rules.
 
 Subclassing the Account class
 ---------------------------------
-To use the Account class, normally application SHOULD create its own subclass, such as::
+To use the Account class, normally application SHOULD create its own subclass, in order to receive notifications for the account. For example:
+
+.. code-block:: c++
 
     class MyAccount : public Account
@@ -26 +27 @@
             cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=")
                  << prm.code << endl;
-
         }
     
@@ -32 +32 @@
         {
             Call *call = new MyCall(*this, iprm.callId);
-            // Delete the call, which will also hangup the call
+
+            // Just hangup for now
+            CallOpParam op;
+            op.statusCode = PJSIP_SC_DECLINE;
+            call->hangup(op);
+            
+            // And delete the call
             delete call;
         }
@@ -54 +60 @@
 Creating Userless Accounts
 --------------------------
-A userless account identifies a particular SIP endpoint rather than a particular user. Some other SIP softphones may call this peer-to-peer mode, which means that we are calling another computer via its address rather than calling a particular user ID.
-
-So for example, we might identify ourselves as "sip:192.168.0.15" (a userless account) rather than, say, "sip:bennylp@pjsip.org".
-
-In pjsua, a userless account corresponds to a particular transport. Creating userless account is very simple, all we need is the transport ID which is returned by ​Endpoint.transportCreate() method as explained in previous chapter.
-
-Here's a snippet::
+A userless account identifies a particular SIP endpoint rather than a particular user. Some other SIP softphones may call this peer-to-peer mode, which means that we are calling another computer via its address rather than calling a particular user ID. For example, we might identify ourselves as "sip:192.168.0.15" (a userless account) rather than, say, "sip:alice@pjsip.org".
+
+In the lower layer PJSUA-LIB API, a userless account is associated with a SIP transport, and is created with ``pjsua_acc_add_local()`` API. This concept has been deprecated in PJSUA2, and rather, a userless account is a "normal" account with a userless ID URI (e.g. "sip:192.168.0.15") and without registration. Thus creating a userless account is exactly the same as creating "normal" account.
+
+
+Creating Account
+----------------
+We need to configure AccountConfig and call Account.create() to create the account. At the very minimum, pjsua only requires the account's ID, which is an URI to identify the account (or in SIP terms, it's called Address of Record/AOR). Here's a snippet:
+
+.. code-block:: c++
 
     AccountConfig acc_cfg;
-    acc_cfg.sipConfig.transportId = tid;
+    acc_cfg.idUri = "sip:test1@pjsip.org";
+
     MyAccount *acc = new MyAccount;
     try {
         acc->create(acc_cfg);
     } catch(Error& err) {
-        cout << "Account creation error: " << err.reason << endl;
+        cout << "Account creation error: " << err.info() << endl;
     }
 
-Once the account is created, you can use the instance as a normal account. More will be explained later.
-
-Accounts created this way will have its URI derived from the transport address. For example, if the transport address is "192.168.0.15:5080", then the account's URI for UDP transport will be "sip:192.168.0.15:5080", or "sip:192.168.0.15:5080;transport=tcp" for TCP transport.
-
-Creating Account
-----------------
-For the "normal" account, we need to configure ​AccountConfig and call ​Account.create() to create the account.
-
-At the very minimum, pjsua only requires the account's ID, which is an URI to identify the account (or in SIP terms, it's called Address of Record/AOR). Here's a snippet::
+The account created above doesn't do anything except to provide identity in the "From:" header for outgoing requests. The account will not register to SIP server or anything.
+
+Typically you will want the account to authenticate and register to your SIP server so that you can receive incoming calls. To do that you will need to configure some more settings in your AccountConfig, something like this:
+
+.. code-block:: c++
 
     AccountConfig acc_cfg;
     acc_cfg.idUri = "sip:test1@pjsip.org";
+    acc_cfg.regConfig.registrarUri = "sip:pjsip.org";
+    acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "secret1") );
+
     MyAccount *acc = new MyAccount;
     try {
         acc->create(acc_cfg);
     } catch(Error& err) {
-        cout << "Account creation error: " << err.reason << endl;
-    }
-
-The account created above doesn't do anything except to provide identity in the "From:" header for outgoing requests. The account will not register to SIP server or anything.
-
-Typically you will want the account to authenticate and register to your SIP server so that you can receive incoming calls. To do that you will need to configure some more settings in your ​AccountConfig, something like this::
-
-    AccountConfig acc_cfg;
-    acc_cfg.idUri = "sip:test1@pjsip.org";
-    acc_cfg.regConfig.registrarUri = "sip:pjsip.org";
-    acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "test1") );
-    MyAccount *acc = new MyAccount;
-    try {
-        acc->create(acc_cfg);
-    } catch(Error& err) {
-        cout << "Account creation error: " << err.reason << endl;
+        cout << "Account creation error: " << err.info() << endl;
     }
 
 Account Configurations
 -----------------------
-There are many more settings that can be specified in ​AccountConfig, like:
+There are many more settings that can be specified in AccountConfig, like:
 
 - AccountRegConfig, to specify registration settings, such as registrar server and retry interval.
@@ -118 +112 @@
 - AccountVideoConfig, to specify video settings, such as default capture and render device.
 
-Please see ​AccountConfig reference documentation for more info.
+Please see AccountConfig reference documentation for more info.
 
 Account Operations
 --------------------------------------
-Some of the operations to the ​Account object:
-
-- add buddy objects
-- set account's presence online status
-- stop/start SIP registration
-
-Please see the reference documentation for Account for more info. Calls, presence, and buddy list will be explained in later sections.
-
-
+Some of the operations to the Account object:
+
+- manage registration
+- manage buddies/contacts
+- manage presence online status
+
+Please see the reference documentation for Account for more info. Calls, presence, and buddy will be explained in later chapters.
+
+
+Class Reference
+---------------
+Account
++++++++
+.. doxygenclass:: pj::Account
+        :path: xml
+        :members:
+
+AccountInfo
++++++++++++
+.. doxygenstruct:: pj::AccountInfo
+        :path: xml
+
+Account Settings
+++++++++++++++++
+AccountConfig
+~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountConfig
+        :path: xml
+
+AccoutRegConfig
+~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountRegConfig
+        :path: xml
+
+AccountSipConfig
+~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountSipConfig
+        :path: xml
+
+AccountCallConfig
+~~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountCallConfig
+        :path: xml
+
+AccountPresConfig
+~~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountPresConfig
+        :path: xml
+
+AccountMwiConfig
+~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountMwiConfig
+        :path: xml
+
+AccountNatConfig
+~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountNatConfig
+        :path: xml
+
+AccountMediaConfig
+~~~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountMediaConfig
+        :path: xml
+
+AccountVideoConfig
+~~~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::AccountVideoConfig
+        :path: xml
+
+
+Callback Parameters
++++++++++++++++++++
+.. doxygenstruct:: pj::OnIncomingCallParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnRegStartedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnRegStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnIncomingSubscribeParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnInstantMessageParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnInstantMessageStatusParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnTypingIndicationParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnMwiInfoParam
+        :path: xml
+
+.. doxygenstruct:: pj::PresNotifyParam
+        :path: xml
+
+Other
++++++
+.. doxygenclass:: pj::FindBuddyMatch
+        :path: xml
+        :members:
+

pjproject/trunk/doc/pjsip-book/call.rst

@@ -1 @@
-
 
 Calls
 =====
-Calls are represented by ​Call class.
+Calls are represented by Call class.
 
 Subclassing the Call Class
 ------------------------------------
-To use the Call class, normally application SHOULD create its own subclass, such as::
+To use the Call class, normally application SHOULD create its own subclass, such as:
+
+.. code-block:: c++
 
     class MyCall : public Call
@@ -30 +31 @@
 Making Outgoing Calls
 --------------------------------------
-Making outgoing call is simple, just invoke ​makeCall() method of the Call object. Assuming you have the Account object as acc variable and destination URI string in dst_uri, you can initiate outgoing call with the snippet below::
+Making outgoing call is simple, just invoke makeCall() method of the Call object. Assuming you have the Account object as acc variable and destination URI string in dest_uri, you can initiate outgoing call with the snippet below:
+
+.. code-block:: c++
 
     Call *call = new MyCall(*acc);
@@ -37 +40 @@
         call->makeCall(dest_uri, prm);
     } catch(Error& err) {
-    }
-
-The snippet above creates a Call object and initiates outgoing call to dst_uri using the default call settings. Subsequent operations to the call can use the method in the ​call instance, and events to the call will be reported to the callback. More on the callback will be explained a bit later.
+        cout << err.info() << endl;
+    }
+
+The snippet above creates a Call object and initiates outgoing call to dest_uri using the default call settings. Subsequent operations to the call can use the method in the call instance, and events to the call will be reported to the callback. More on the callback will be explained a bit later.
 
 Receiving Incoming Calls
 --------------------------------------
-Incoming calls are reported as ​onIncomingCall() of the ​Account class. You must derive a class from the Account class to handle incoming calls.
-
-Below is a sample code of the callback implementation::
+Incoming calls are reported as onIncomingCall() of the Account class. You must derive a class from the Account class to handle incoming calls.
+
+Below is a sample code of the callback implementation:
+
+.. code-block:: c++
 
     void MyAccount::onIncomingCall(OnIncomingCallParam &iprm)
@@ -51 +57 @@
         Call *call = new MyCall(*this, iprm.callId);
         CallOpParam prm;
-        prm.statusCode = (pjsip_status_code)200;
+        prm.statusCode = PJSIP_SC_OK;
         call->answer(prm);
     }
 
-For incoming calls, the call instance is created in the callback parameter as shown above. Application should make sure to store the call instance during the lifetime of the call (that is until the call is disconnected).
+For incoming calls, the call instance is created in the callback function as shown above. Application should make sure to store the call instance during the lifetime of the call (that is until the call is disconnected).
 
 Call Properties
+----------------
+All call properties such as state, media state, remote peer information, etc. are stored as CallInfo class, which can be retrieved from the call object with using getInfo() method of the Call.
+
+Call Disconnection
 -------------------
-All call properties such as state, media state, remote peer information, etc. are stored as ​CallInfo class, which can be retrieved from the call object with using getInfo() method of the Call.
-
-Call Disconnection
---------------------------------------
 Call disconnection event is a special event since once the callback that reports this event returns, the call is no longer valid and any operations invoked to the call object will raise error exception. Thus, it is recommended to delete the call object inside the callback.
 
-The call disconnection is reported in ​onCallState() method of ​Call and it can be detected as follows::
+The call disconnection is reported in onCallState() method of Call and it can be detected as follows:
+
+.. code-block:: c++
 
     void MyCall::onCallState(OnCallStateParam &prm)
@@ -78 +86 @@
 Working with Call's Audio Media
 -------------------------------------------------
-You can only operate with the call's audio media (e.g. connecting the call to the sound device in the conference bridge) when the call's audio media is ready (or active). The changes to the call's media state is reported in ​onCallMediaState() callback, and if the call’s audio media is ready (or active) the function getMedia() will return a valid audio media.
-
-Below is a sample code to connect the call to the sound device when the media is active::
+You can only operate with the call's audio media (e.g. connecting the call to the sound device in the conference bridge) when the call's audio media is ready (or active). The changes to the call's media state is reported in onCallMediaState() callback, and if the calls audio media is ready (or active) the function Call.getMedia() will return a valid audio media.
+
+Below is a sample code to connect the call to the sound device when the media is active:
+
+.. code-block:: c++
 
     void MyCall::onCallMediaState(OnCallMediaStateParam &prm)
     {
         CallInfo ci = getInfo();
-        // Iterate all medias
+        // Iterate all the call medias
         for (unsigned i = 0; i < ci.media.size(); i++) {
-            if (getMedia(i)) { // Check if the media is valid
-                AudioMedia *aud_med = getMedia(i);
+            if (ci.media[i].type==PJMEDIA_TYPE_AUDIO && getMedia(i)) {
+                AudioMedia *aud_med = (AudioMedia *)getMedia(i);
+
                 // Connect the call audio media to sound device
-                aud_med->startTransmit();
-                ->startTransmit(*aud_med);
+                AudDevManager& mgr = Endpoint::instance().audDevManager();
+                aud_med->startTransmit(mgr.getPlaybackDevMedia());
+                mgr.getCaptureDevMedia().startTransmit(*aud_med);
             }
         }
@@ -99 +111 @@
 
 Call Operations
---------------------------------------
-Some of the operations to the Call object, such as making outgoing call, answering, holding, sending re-INVITE, etc. Please see the reference documentation of Call for more info.
-
+-------------------
+You can invoke operations to the Call object, such as hanging up, putting the call on hold, sending re-INVITE, etc. Please see the reference documentation of Call for more info.
+
+Instant Messaging(IM)
+---------------------
+You can send IM within a call using Call.sendInstantMessage(). The transmission status of outgoing instant messages is reported in Call.onInstantMessageStatus() callback method.
+
+In addition to sending instant messages, you can also send typing indication using Call.sendTypingIndication().
+
+Incoming IM and typing indication received within a call will be reported in the callback functions Call.onInstantMessage() and Call.onTypingIndication().
+
+Alternatively, you can send IM and typing indication outside a call by using Buddy.sendInstantMessage() and Buddy.sendTypingIndication(). For more information, please see Presence documentation.
+
+
+Class Reference
+---------------
+Call
+++++
+.. doxygenclass:: pj::Call
+        :path: xml
+        :members:
+
+Settings
+++++++++
+.. doxygenstruct:: pj::CallSetting
+        :path: xml
+        
+
+Info and Statistics
++++++++++++++++++++
+.. doxygenstruct:: pj::CallInfo
+        :path: xml
+        
+.. doxygenstruct:: pj::CallMediaInfo
+        :path: xml
+        
+.. doxygenstruct:: pj::StreamInfo
+        :path: xml
+        
+.. doxygenstruct:: pj::StreamStat
+        :path: xml
+
+.. doxygenstruct:: pj::JbufState
+        :path: xml
+
+.. doxygenstruct:: pj::RtcpStat
+        :path: xml
+
+.. doxygenstruct:: pj::RtcpStreamStat
+        :path: xml
+
+.. doxygenstruct:: pj::MathStat
+        :path: xml
+
+.. doxygenstruct:: pj::MediaTransportInfo
+        :path: xml
+
+
+Callback Parameters
++++++++++++++++++++
+.. doxygenstruct:: pj::OnCallStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallTsxStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallMediaStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallSdpCreatedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnStreamCreatedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnStreamDestroyedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnDtmfDigitParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallTransferRequestParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallTransferStatusParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallReplaceRequestParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallReplacedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallRxOfferParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallRedirectedParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallMediaEventParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCallMediaTransportStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnCreateMediaTransportParam
+        :path: xml
+
+.. doxygenstruct:: pj::CallOpParam
+        :path: xml
+
+.. doxygenstruct:: pj::CallSendRequestParam
+        :path: xml
+
+.. doxygenstruct:: pj::CallVidSetStreamParam
+        :path: xml
+
+Other
++++++
+.. doxygenstruct:: pj::MediaEvent
+        :path: xml
+
+.. doxygenstruct:: pj::MediaFmtChangedEvent
+        :path: xml
+
+.. doxygenstruct:: pj::SdpSession
+        :path: xml
+
+.. doxygenstruct:: pj::RtcpSdes
+        :path: xml
+
+

pjproject/trunk/doc/pjsip-book/consider.rst

@@ -1 +1 @@
 
 
-
-Development Considerations
-**************************
-
-Let's review various aspects that you need to consider when developing your application.
-
-
-Target Platforms
-================
-Platform selection will affect all aspects of development, and here we will cover  considerations for each platforms that we support.
+Development Guidelines and Considerations
+*****************************************
+
+Development Guidelines
+======================
+
+Preparation
+------------
+* **Essential:** Familiarise yourself with SIP. You don't need to be an expert, but SIP knowledge is essential. 
+* Check out our features in `Datasheet <http://trac.pjsip.org/repos/wiki/PJSIP-Datasheet>`_. Other features may be provided by our `community <http://trac.pjsip.org/repos/wiki/Projects_Using_PJSIP>`_.
+* All PJSIP documentation is indexed in our `Trac site <http://trac.pjsip.org/repos>`_.
+
+
+Development
+-------------
+* **Essential:** Interactive debugging capability is essential during development
+* Start with default settings in `<pj/config_site_sample.h>`.
+
+Coding Style
+-------------
+**Essential:** set your editor to use 8 characters tab size in order to see PJSIP source correctly.
+
+These below are PJSIP coding style. You don't need to follow it unless you are submitting patches to PJSIP:
+
+* indentation uses tabs and spaces. Tab size is 8 characters, indentation 4.
+* all public API in header file must be documented in Doxygen format.
+* other than that, we mostly just use `K & R style <http://en.wikipedia.org/wiki/1_true_brace_style#K.26R_style>`_, which is the only correct style anyway.
+
+
+Deployment
+-----------
+* **Essential:** Logging is essential when troubleshooting any problems. The application MUST be equipped with logging capability. Enable PJSIP log at level 5.
+
+
+Platform Consideration
+========================
+Platform selection is usually driven by business motives. The selection will affect all aspects of development, and here we will cover  considerations for each platforms that we support.
 
 Windows Desktop

pjproject/trunk/doc/pjsip-book/endpoint.rst

@@ -1 @@
-
 
 Endpoint
 ************
-The ​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:
+The 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, and similarly, once this class is destroyed, application must NOT call any library API. This class is the core class of PJSUA2, and it provides the following functions:
 
 - Starting up and shutting down
 - Customization of configurations, such as core UA (User Agent) SIP configuration, media configuration, and logging configuration
 
-This section will describe the functions above.
+This chapter will describe the functions above.
 
 To use the Endpoint class, normally application does not need to subclass it unless:
 
-- application wants to implement/override Endpoint’s callback methods to get the events such as transport state change or NAT detection completion, or
+- application wants to implement/override Endpoints callback methods to get the events such as transport state change or NAT detection completion, or
 - 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.
 
@@ -25 +24 @@
 Creating the Library
 ----------------------
-Create the library by calling its libCreate() method::
+Create the library by calling its libCreate() method:
+
+.. code-block:: c++
 
     try {
         ep->libCreate();
     } catch(Error& err) {
-        cout << "Startup error: " << err.reason << endl;
+        cout << "Startup error: " << err.info() << endl;
     }
 
@@ -41 +42 @@
 
 - UAConfig, to specify core SIP user agent settings.
-- MediaConfig, to specify various media settings, including ICE and TURN.
+- MediaConfig, to specify various media *global* settings
 - LogConfig, to customize logging settings.
 
-To customize the settings, create instance of EpConfig class and specify them during the endpoint initialization (will be explained more later), for example::
+Note that some settings can be further specified on per account basis, in the AccountConfig.
+
+To customize the settings, create instance of EpConfig class and specify them during the endpoint initialization (will be explained more later), for example:
+
+.. code-block:: c++
 
     EpConfig ep_cfg;
@@ -51 +56 @@
     ep_cfg.mediaConfig.sndClockRate = 16000;
 
-Next, you can initialize the library by calling libInit()::
+Next, you can initialize the library by calling libInit():
+
+.. code-block:: c++
 
     try {
@@ -58 +65 @@
         ep->libInit(ep_cfg);
     } catch(Error& err) {
-        cout << "Initialization error: " << err.reason << endl;
+        cout << "Initialization error: " << err.info() << endl;
     }
 
@@ -65 +72 @@
 Creating One or More Transports
 --------------------------------------------------
-Application needs to create one or more ​transports before it can send or receive SIP messages::
+Application needs to create one or more transports before it can send or receive SIP messages:
+
+.. code-block:: c++
 
     try {
@@ -72 +81 @@
         TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_UDP, tcfg);
     } catch(Error& err) {
-        cout << "Transport creation error: " << err.reason << endl;
+        cout << "Transport creation error: " << err.info() << endl;
     }
 
-The 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.
+The 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.
 
-There 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.
+There 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.
 
 Starting the Library
 --------------------
-Now 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::
+Now 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:
+
+.. code-block:: c++
 
     try {
         ep->libStart();
     } catch(Error& err) {
-        cout << "Startup error: " << err.reason << endl;
+        cout << "Startup error: " << err.info() << endl;
     }
 
 Shutting Down the Library
 --------------------------------------
-Once 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()::
+Once the application exits, the library needs to be shutdown so that resources can be released back to the operating system. Although this can be done by deleting the Endpoint instance, which will internally call libDestroy(), it is better to call it manually because on Java or Python there are problems with garbage collection as explained earlier:
 
+.. code-block:: c++
+
+    ep->libDestroy();
     delete ep;
 
+
+Class Reference
+---------------
+The Endpoint
+++++++++++++
+.. doxygenclass:: pj::Endpoint
+        :path: xml
+        :members:
+
+Endpoint Configurations
++++++++++++++++++++++++
+Endpoint
+~~~~~~~~
+.. doxygenstruct:: pj::EpConfig
+        :path: xml
+
+Media
+~~~~~
+.. doxygenstruct:: pj::MediaConfig
+        :path: xml
+
+Logging
+~~~~~~~
+.. doxygenstruct:: pj::LogConfig
+        :path: xml
+
+.. doxygenclass:: pj::LogWriter
+        :path: xml
+        :members:
+
+.. doxygenstruct:: pj::LogEntry
+        :path: xml
+
+User Agent
+~~~~~~~~~~
+.. doxygenstruct:: pj::UaConfig
+        :path: xml
+
+
+Callback Parameters
++++++++++++++++++++
+.. doxygenstruct:: pj::OnNatDetectionCompleteParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnNatCheckStunServersCompleteParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnTimerParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnTransportStateParam
+        :path: xml
+
+.. doxygenstruct:: pj::OnSelectAccountParam
+        :path: xml
+
+
+Other
++++++
+.. doxygenstruct:: pj::PendingJob
+        :path: xml
+

pjproject/trunk/doc/pjsip-book/fetch_trac.py

@@ -1 +1 @@
 import urllib2
 import sys
+import unicodedata
 
 def fetch_rst(url):
@@ -7 +8 @@
                 
         fd = urllib2.urlopen(req, timeout=30)
-        body = fd.read()                
+        body = fd.read()
+        body = body.replace("\r\n", "\n")
+
+        body = body.decode('utf8', 'ignore').encode('ascii', 'ignore')
 
         pos = body.find("{{{")
@@ -79 +83 @@
         pages = process_index('index')
         for page in pages:
+                #if not 'endpoint' in page:
+                #       continue
                 url = url_format % (page)
                 fetch_rst(url)

pjproject/trunk/doc/pjsip-book/index.rst

@@ -1 @@
-
 .. The PJSIP Book documentation master file, created by
    sphinx-quickstart on Sat Nov 30 06:36:26 2013.
@@ -5 +4 @@
    contain the root `toctree` directive.
 
-Welcome to The PJSIP Book's documentation!
+The PJSIP Book
 ==========================================
 
@@ -12 +11 @@
 .. toctree::
    :maxdepth: 2
+   :numbered: 1
 
    intro
    consider
    intro_pjsua2
+   getting_started
    endpoint
    account

pjproject/trunk/doc/pjsip-book/intro.rst

@@ -1 @@
-
 
 Introduction to PJSUA2
@@ -5 +4 @@
 This documentation is intended for developers looking to develop Session Initiation Protocol (SIP) based client application. Some knowledge on SIP is definitely required, and of course some programming experience. Prior knowledge of PJSUA C API is not needed, although it will probably help.
 
-This PJSUA2 module provides very high level API to do SIP calls, presence, and instant messaging, as well as handling media and NAT traversal. Knowledge of SIP protocol details (such as the grammar, transaction, dialog, and whatnot) are not required, however you should know how SIP works in general and particularly how to configure SIP clients to, e.g. register to a SIP provider, specify SIP URI to make call to, and so on, to use the module.
+This PJSUA2 module provides very high level C++ API to do SIP calls, presence, and instant messaging, as well as handling media and NAT traversal. Knowledge of SIP protocol details (such as the grammar, transaction, dialog, and whatnot) are not required, however you should know how SIP works in general and particularly how to configure SIP clients to, e.g. register to a SIP provider, specify SIP URI to make call to, and so on, to use the module.
 
 Getting Started with PJSIP
 ==============================
-To begin using PJSIP
-http://trac.pjsip.org/repos/wiki/Getting-Started
+Check `PJSIP's Features List`_ to make sure that it has the features that you require.
+
+.. _`PJSIP's Features List`: http://trac.pjsip.org/repos/wiki/PJSIP-Datasheet
+
+Then to begin using PJSIP, the `Getting Started Guide`_ contains instructions to acquire and build PJSIP on various platforms that we support.
+
+.. _`Getting Started Guide`: http://trac.pjsip.org/repos/wiki/Getting-Started 
 
 PJSIP Info and Documentation
 ================================
-PJSIP General Wiki:
-http://trac.pjsip.org/repos/wiki
+To get other relevant info and documentations about PJSIP, you can visit:
 
-PJSIP FAQ:
-http://trac.pjsip.org/repos/wiki/FAQ
+- `PJSIP General Wiki`_
+- `PJSIP FAQ`_
+- `PJSIP Reference Manual`_ - please see Reference Manual section
 
-PJSIP Reference Manual:
-http://trac.pjsip.org/repos/wiki - Reference Manual
+.. _`PJSIP General Wiki`: http://trac.pjsip.org/repos/wiki
+.. _`PJSIP FAQ`: http://trac.pjsip.org/repos/wiki/FAQ
+.. _`PJSIP Reference Manual`: http://trac.pjsip.org/repos/wiki
 
 Building PJSUA2
 =================
-PJSUA2 API declaration can be found in pjproject/pjsip/include/pjsua2 while the source codes are located in pjproject/pjsip/src/pjsua2. It will be automatically built when you compile PJSIP.
+PJSUA2 API declaration can be found in ``pjsip/include/pjsua2`` while the source codes are located in ``pjsip/src/pjsua2``. It will be automatically built when you compile PJSIP.
 
 PJSUA2 Language Binding Support
 ===================================
-Optional if you want to:
-​SWIG (minimum version 2.0.5)
+The PJSUA2 API is also available for other programming languages via SWIG binding, such as Java and Python.
 

pjproject/trunk/doc/pjsip-book/intro_pjsua2.rst

@@ -1 @@
-
 PJSUA2-High Level API
 ******************************
-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.
+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.
 
 PJSUA2 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.
+
+
+Building PJSUA2
+======================
+The PJSUA2 C++ library will be built by default by PJSIP build system.
+
+The SWIG modules for Python and Java are built by invoking ``make`` manually from ``pjsip-apps/src/swig`` directory.
 
 
@@ -21 +27 @@
 Media
 ----------
-This class represents a media element which is capable to either produce media or takes media.
+This is an abstract base class that represents a media element which is capable to either produce media or takes media. It is then subclassed into ``AudioMedia``, which is then subclassed into concrete classes such as ``AudioMediaPlayer`` and ``AudioMediaRecorder``.
 
 Call
 ------
-This class is used to manipulate calls, such as to answer the call, hangup the call, put the call on hold, transfer the call, etc.
+This class represents an ongoing call (or speaking technically, an INVITE session) and can be used to manipulate it, such as to answer the call, hangup the call, put the call on hold, transfer the call, etc.
 
 Buddy
@@ -35 +41 @@
 Class Usage Patterns
 ---------------------
-With 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.
+With 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.
+
+Error Handling
+---------------
+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.
+
+Asynchronous Operations
+-------------------------
+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.
+
+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.
+
+Threading
+----------
+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.
+
+Problems with Garbage Collection
+--------------------------------
+Garbage 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:
+
+- it delays the destruction of objects (including PJSUA2 objects), causing the code in object's destructor to be executed out of order
+- the GC operation may run on different thread not previously registered to PJLIB, causing assertion
+
+Due 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.
+
+For 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):
+
+.. code-block:: c++
+
+    acc.delete();
+
+
+
 
 Objects Persistence
 ---------------------
-PJSUA2 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.
+PJSUA2 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 ([http://tools.ietf.org/html/rfc4627 RFC 4627]), but the framework allows application to extend the API to support other document formats.
 
-As 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:
+As 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. Heres an example to save a config to a file:
 
 .. code-block:: c++
@@ -50 +88 @@
     epCfg.uaConfig.userAgent = "Just JSON Test";
     jDoc.writeObject(epCfg);
-    jDoc.saveFile(“jsontest.js”);
+    jDoc.saveFile("jsontest.js");
 
 To load from the file:
@@ -61 +99 @@
     jDoc.readObject(epCfg);
 
-Error Handling
----------------
-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.
 
-Asynchronous Operations
--------------------------
-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.
-
-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.
-
-Threading
-----------
-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 should be thread safe.
-
-
-Using in C++ Application
-========================
-As 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.
-
-Here 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.
-
-.. code-block:: c++
-    
-  #include <pjsua2.hpp>
-  #include <iostream>
-  
-  using namespace pj;
-  
-  // Subclass to extend the Account and get notifications etc.
-  class MyAccount : public Account {
-  public:
-      virtual void onRegState(OnRegStateParam &prm) {
-          AccountInfo ai = getInfo();
-          std::cout << (ai.regIsActive? "*** Register:" : "*** Unregister:")
-                    << " code=" << prm.code << std::endl;
-      }
-  };
-
-  int main()
-  {
-      Endpoint ep;
-      
-      ep.libCreate();
-      
-      // Initialize endpoint
-      EpConfig ep_cfg;
-      ep_cfg.uaConfig.userAgent = "pjsua2-hello";
-      ep.libInit( ep_cfg );
-      
-      // Create SIP transport. Error handling sample is shown
-      TransportConfig tcfg;
-      tcfg.port = 5060;
-      try {
-          ep.transportCreate(PJSIP_TRANSPORT_UDP, tcfg);
-      } catch (Error &err) {
-          std::cout << err.info() << std::endl;
-          return 1;
-      }
-      
-      // Start the library (worker threads etc)
-      ep.libStart();
-      std::cout << "*** PJSUA2 STARTED ***" << std::endl;
-      
-      // Configure an AccountConfig
-      AccountConfig acfg;
-      acfg.idUri = "sip:test@pjsip.org";
-      acfg.regConfig.registrarUri = "sip:pjsip.org";
-      AuthCredInfo cred("digest", "*", "test", 0, "secret");
-      acfg.sipConfig.authCreds.push_back( cred );
-      
-      // Create the account
-      MyAccount *acc = new MyAccount;
-      acc->create(acfg);
-      
-      // Here we don't have anything else to do..
-      pj_thread_sleep(10000);
-      
-      // Delete the account. This will unregister from server
-      delete acc;
-      
-      // This will implicitly shutdown the library
-      return 0;
-  }
-
-
-Using in Python Application
-===========================
-
-
-
-Using in Java Application
-=========================
-
-
-
-

pjproject/trunk/doc/pjsip-book/media.rst

@@ -1 @@
-
 
 Media
 =====
-Media objects are objects that are capable to either produce media or takes media. In ​PJMEDIA terms, these objects are implemented as media ports (​pjmedia_port).
+Media objects are objects that are capable to either produce media or takes media.
 
 An important subclass of Media is AudioMedia which represents audio media. There are several type of audio media objects supported in PJSUA2:
 
-- CallAudioMedia, to transmit and receive audio to/from remote person.
+- Capture device's AudioMedia, to capture audio from the sound device.
+- Playback device's AudioMedia, to play audio to the sound device.
+- Call's AudioMedia, to transmit and receive audio to/from remote person.
 - AudioMediaPlayer, to play WAV file(s).
 - AudioMediaRecorder, to record audio to a WAV file.
@@ -15 +16 @@
 The Audio Conference Bridge
 ----------------------------
-The conference bridge provides a simple but yet powerful concept to manage audio flow between the audio medias. The principle is very simple, that is you connect audio source to audio destination, and the bridge will make the audio flows from the source to destination, and that's it. If more than one sources are transmitting to the same destination, then the audio from the sources will be mixed. If one source is transmitting to more than one destinations, the bridge will take care of duplicating the audio from the source to the multiple destinations.
-
-In ​PJSUA2, all audio media objects are plugged-in to the central conference bridge for easier manipulation. A plugged-in audio media will not be connected to anything, so media will not flow from/to any objects. An audio media source can start/stop the transmission to a destination by using the API AudioMedia.startTransmit() / AudioMedia.stopTransmit().
-
-An audio media object plugged-in to the conference bridge will be given a port ID number that identifies the object in the bridge. Application can use the API AudioMedia.getPortId() to retrieve the port ID. Normally, application should not need to worry about the port ID (as all will be taken care of by the bridge) unless application want to create its own custom audio media.
+The conference bridge provides a simple but yet powerful concept to manage audio flow between the audio medias. The principle is very simple, that is you connect audio source to audio destination, and the bridge will make the audio flows from the source to destination, and that's it. If more than one sources are transmitting to the same destination, then the audio from the sources will be mixed. If one source is transmitting to more than one destinations, the bridge will take care of duplicating the audio from the source to the multiple destinations. The bridge will even take care medias with different clock rates and ptime.
+
+In PJSUA2, all audio media objects are plugged-in to the central conference bridge for easier manipulation. At first, a plugged-in audio media will not be connected to anything, so media will not flow from/to any objects. An audio media source can start/stop the transmission to a destination by using the API AudioMedia.startTransmit() / AudioMedia.stopTransmit().
+
+An audio media object plugged-in to the conference bridge will be given a port ID number that identifies the object in the bridge. Application can use the API AudioMedia.getPortId() to retrieve the port ID. Normally, application should not need to worry about the conference bridge and its port ID (as all will be taken care of by the Media class) unless application want to create its own custom audio media.
 
 Playing a WAV File
 ++++++++++++++++++
-To playback the WAV file to the speaker, just start the transmission of the WAV playback object to the sound device::
+To playback the WAV file to the sound device, just start the transmission of the WAV playback object to the sound device's playback media:
+
+.. code-block:: c++
 
     AudioMediaPlayer player;
-    try {
-        player.createPlayer(“file.wav”);
-        player.startTransmit();
-    } catch(Error& err) {
-    }
-
-Once you're done with the playback, just stop the transmission n to stop the playback::
-
-    try {
-        player.stopTransmit();
-    } catch(Error& err) {
-    }
+    AudioMedia& play_med = Endpoint::instance().audDevManager().getPlaybackDevMedia();
+    try {
+        player.createPlayer("file.wav");
+        player.startTransmit(play_med);
+    } catch(Error& err) {
+    }
+
+By default, the WAV file will be played in a loop. To disable the loop, specify ``PJMEDIA_FILE_NO_LOOP`` when creating the player:
+
+.. code-block:: c++
+
+        player.createPlayer("file.wav", PJMEDIA_FILE_NO_LOOP);
+
+Without looping, silence will be played once the playback has reached the end of the WAV file.
+
+Once you're done with the playback, just stop the transmission to stop the playback:
+
+.. code-block:: c++
+
+    try {
+        player.stopTransmit(play_med);
+    } catch(Error& err) {
+    }
+
+Resuming the transmission after the playback is stopped will resume playback from the last play position. Use ``player.setPos()`` to set playback position to a desired location.
+
 
 Recording to WAV File
 +++++++++++++++++++++
-Or if you want to record the microphone to the WAV file, simply do this::
+Or if you want to record the audio from the sound device to the WAV file, simply do this:
+
+.. code-block:: c++
 
     AudioMediaRecorder recorder;
-    try {
-        recorder.createRecorder(“file.wav”);
-        .startTransmit(recorder);
-    } catch(Error& err) {
-    }
-
-And the media will flow from the sound device to the WAV record file. As usual, to stop or pause recording, just stop the transmission::
-
-    try {
-       .stopTransmit(recorder);
-    } catch(Error& err) {
-    }
-
-(Note that stopping the transmission to the WAV recorder as above does not close the WAV file, and you can resume recording by connecting a source to the WAV recorder again. You cannot playback the recorded WAV file before you close it.)
+    AudioMedia& cap_med = Endpoint::instance().audDevManager().getCaptureDevMedia();
+    try {
+        recorder.createRecorder("file.wav");
+        cap_med.startTransmit(recorder);
+    } catch(Error& err) {
+    }
+
+And the media will flow from the sound device to the WAV record file. As usual, to stop or pause recording, just stop the transmission:
+
+.. code-block:: c++
+
+    try {
+       cap_med.stopTransmit(recorder);
+    } catch(Error& err) {
+    }
+
+Note that stopping the transmission to the WAV recorder as above does not close the WAV file, and you can resume recording by connecting a source to the WAV recorder again. You cannot playback the recorded WAV file before you close it. To close the WAV recorder, simply delete it:
+
+.. code-block:: c++
+
+    delete recorder;
+
+
+Local Audio Loopback
+++++++++++++++++++++
+A useful test to check whether the local sound device (capture and playback device) is working properly is by transmitting the audio from the capture device directly to the playback device (i.e. local loopback). You can do this by:
+
+.. code-block:: c++
+
+    cap_med.startTransmit(play_med);
+
 
 Looping Audio
 +++++++++++++
-If you want, you can loop the audio of a media object to itself (i.e. the audio received from the object will be transmitted to itself). For example, you can loop the audio of the sound device with::
-
-    .startTransmit();
-
-With the above connection, audio received from the microphone will be played back to the speaker. This is useful to test whether the microphone and speaker are working properly.
-
-You can loop-back audio from any objects, as long as the object has bidirectional media. That means you can loop the call's audio media, so that audio received from the remote person will be transmitted back to her/him. But you can't loop the WAV player or recorder since these objects can only play or record and not both.
+If you want, you can loop the audio of an audio media object to itself (i.e. the audio received from the object will be transmitted to itself). You can loop-back audio from any objects, as long as the object has bidirectional media. That means you can loop the call's audio media, so that audio received from the remote person will be transmitted back to her/him. But you can't loop the WAV player or recorder since these objects can only play or record and not both.
 
 Normal Call
 +++++++++++
 
-A single call can has several audio medias. Application can retrieve the audio media by using the API Call.getMedia()::
-
-    AudioMedia *aud_med = (AudioMedia *)call.getMedia(0);
-
-In the above, we assume that the audio media is located in index 0. Of course on a real application, we should iterate the medias to find the correct media index by checking whether the media returned by getMedia() is valid. More on this will be explained later in the Call section. Then for a normal call, we would want to establish bidirectional audio with the remote person, which can be done easily by connecting the sound device and the call audio media and vice versa::
-
-    // This will connect the sound device/mic to the call audio media
-    ->startTransmit(*aud_med);
-
-    // And this will connect the call audio media to the sound device/speaker
-    aud_med->startTransmit();
+A single call can have more than one media (for example, audio and video). Application can retrieve the audio media by using the API Call.getMedia(). Then for a normal call, we would want to establish bidirectional audio with the remote person, which can be done easily by connecting the sound device and the call audio media and vice versa:
+
+.. code-block:: c++
+
+    CallInfo ci = call.getInfo();
+    AudioMedia *aud_med = NULL;
+
+    // Find out which media index is the audio
+    for (unsigned i=0; i<ci.media.size(); ++i) {
+        if (ci.media[i].type == PJMEDIA_TYPE_AUDIO) {
+            aud_med = (AudioMedia *)call.getMedia(i);
+            break;
+        }
+    }
+
+    if (aud_med) {
+        // This will connect the sound device/mic to the call audio media
+        cap_med.startTransmit(*aud_med);
+
+        // And this will connect the call audio media to the sound device/speaker
+        aud_med->startTransmit(play_med);
+    }
+
+
 
 Second Call
 +++++++++++
-Suppose we want to talk with two remote parties at the same time. Since we already have bidirectional media connection with one party, we just need to add bidirectional connection with the other party using the code below::
-
-    AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(0);
-    ->startTransmit(*aud_med2);
-    aud_med2->startTransmit();
+Suppose we want to talk with two remote parties at the same time. Since we already have bidirectional media connection with one party, we just need to add bidirectional connection with the other party using the code below:
+
+.. code-block:: c++
+
+    AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(aud_idx);
+    if (aud_med2) {
+        cap_med->startTransmit(*aud_med2);
+        aud_med2->startTransmit(play_med);
+    }
 
 Now we can talk to both parties at the same time, and we will hear audio from either party. But at this stage, the remote parties can't talk or hear each other (i.e. we're not in full conference mode yet).
@@ -96 +143 @@
 Conference Call
 +++++++++++++++
-To enable both parties talk to each other, just establish bidirectional media between them::
+To enable both parties talk to each other, just establish bidirectional media between them:
+
+.. code-block:: c++
 
     aud_med->startTransmit(*aud_med2);
@@ -106 +155 @@
 ++++++++++++++++++++++++
 
-While doing the conference, it perfectly makes sense to want to record the conference to a WAV file, and all we need to do is to connect the microphone and both calls to the WAV recorder::
-
-    ->startTransmit(recorder);
+While doing the conference, it perfectly makes sense to want to record the conference to a WAV file, and all we need to do is to connect the microphone and both calls to the WAV recorder:
+
+.. code-block:: c++
+
+    cap_med.startTransmit(recorder);
     aud_med->startTransmit(recorder);
     aud_med2->startTransmit(recorder);
 
+
+Audio Device Management
+-----------------------
+Please see `Audio Device Framework <#auddev>`_ below.
+
+
+Class Reference
+---------------
+Media Framework
++++++++++++++++
+Classes
+~~~~~~~
+.. doxygenclass:: pj::Media
+        :path: xml
+        :members:
+
+.. doxygenclass:: pj::AudioMedia
+        :path: xml
+        :members:
+
+.. doxygenclass:: pj::AudioMediaPlayer
+        :path: xml
+        :members:
+
+.. doxygenclass:: pj::AudioMediaRecorder
+        :path: xml
+        :members:
+
+Formats and Info
+~~~~~~~~~~~~~~~~
+.. doxygenstruct:: pj::MediaFormat
+        :path: xml
+
+.. doxygenstruct:: pj::MediaFormatAudio
+        :path: xml
+
+.. doxygenstruct:: pj::MediaFormatVideo
+        :path: xml
+
+.. doxygenstruct:: pj::ConfPortInfo
+        :path: xml
+
+Audio Device Framework
+++++++++++++++++++++++
+Device Manager
+~~~~~~~~~~~~~~
+.. _auddev:
+.. doxygenclass:: pj::AudDevManager
+        :path: xml
+        :members:
+
+Device Info
+~~~~~~~~~~~
+.. doxygenstruct:: pj::AudioDevInfo
+        :path: xml
+

pjproject/trunk/doc/pjsip-book/media_quality.rst

@@ -1 @@
-
 
 Media Quality
@@ -6 +5 @@
 Audio Quality
 =============
+If you experience any problem with the audio quality, you may want to try the steps below:
+
+1. Follow the guide: `Test the sound device using pjsystest`_.
+2. Identify the sound problem and troubleshoot it using the steps described in: `Checking for sound problems`_.
+
+.. _`Checking for sound problems`: http://trac.pjsip.org/repos/wiki/sound-problems
+.. _`Test the sound device using pjsystest`: http://trac.pjsip.org/repos/wiki/Testing_Audio_Device_with_pjsystest
+
+It is probably easier to do the testing using lower level API such as PJSUA since we already have a built-in pjsua sample app located in pjsip-apps/bin to do the testing. However, you can also do the testing in your application using PJSUA2 API such as local audio loopback, recording to WAV file as explained in the Media chapter previously.
 
 Video Quality
 =============
+For video quality problems, the steps are as follows:
 
+1. For lack of video, check account's AccountVideoConfig, especially the fields autoShowIncoming and autoTransmitOutgoing. More about the video API is explained in `Video Users Guide`_.
+2. Check local video preview using PJSUA API as described in `Video Users Guide-Video Preview API`_.
+3. Since video requires a larger bandwidth, we need to check for network impairments as described in `Checking Network Impairments`_. The document is for troubleshooting audio problem but it applies for video as well.
+4. Check the CPU utilization. If the CPU utilization is too high, you can try a different (less CPU-intensive) video codec or reduce the resolution/fps. A general guide on how to reduce CPU utilization can be found here: `FAQ-CPU utilization`_.
+
+.. _`Video Users Guide`: http://trac.pjsip.org/repos/wiki/Video_Users_Guide
+.. _`Video Users Guide-Video Preview API`: http://trac.pjsip.org/repos/wiki/Video_Users_Guide#VideopreviewAPI
+.. _`Checking Network Impairments`: http://trac.pjsip.org/repos/wiki/audio-check-packet-loss
+.. _`FAQ-CPU utilization`: http://trac.pjsip.org/repos/wiki/FAQ#cpu
+

pjproject/trunk/doc/pjsip-book/network_problems.rst

@@ -1 @@
-
 
 Network Problems
@@ -6 +5 @@
 IP Address Change
 =================
+Please see the wiki `Handling IP Address Change`_. Note that the guide is written using PJSUA API as a reference.
+
+.. _`Handling IP Address Change`: https://trac.pjsip.org/repos/wiki/IPAddressChange
 
 Blocked/Filtered Network
 ========================
+Please refer to the wiki `Getting Around Blocked or Filtered VoIP Network`_.
 
+.. _`Getting Around Blocked or Filtered VoIP Network`: https://trac.pjsip.org/repos/wiki/get-around-nat-blocked-traffic-filtering
+

pjproject/trunk/doc/pjsip-book/optimization.rst

@@ -1 @@
-
 
 General Configuration Optimization
@@ -9 +8 @@
 CPU Optimization
 ================
+A general guide on how to reduce CPU utilization can be found here: `FAQ-CPU utilization`_.
 
+.. _`FAQ-CPU utilization`: http://trac.pjsip.org/repos/wiki/FAQ#cpu
+

pjproject/trunk/doc/pjsip-book/presence.rst

@@ -1 @@
-
 
 Buddy (Presence)
 ================
-This class represents a remote buddy (a person, or a SIP endpoint).
-To use the Buddy class, application DOES NOT need to subclass it unless application wants to get the notifications on buddy state change.
+Presence feature in PJSUA2 centers around Buddy class. This class represents a remote buddy (a person, or a SIP endpoint).
 
-Subscribe to Buddy's Presence Status
----------------------------------------------------------
-To subscribe to buddy's presence status, you need to add a buddy object, install callback to handle buddy's event, and start subscribing to buddy's presence status. The snippet below shows a sample code to achieve these::
+Subclassing the Buddy class
+----------------------------
+To use the Buddy class, normally application SHOULD create its own subclass, such as:
 
-  class MyBuddyCallback(pjsua.BuddyCallback):
-    def __init__(self, buddy=None):
-        pjsua.BuddyCallback.__init__(self, buddy)
+.. code-block:: c++
 
-    def on_state(self):
-        print "Buddy", self.buddy.info().uri, "is",
-        print self.buddy.info().online_text
+    class MyBuddy : public Buddy
+    {
+    public:
+        MyBuddy() {}
+        ~MyBuddy() {}
 
-  try:
-    uri = '"Alice" <sip:alice@example.com>'
-    buddy = acc.add_buddy(uri, cb=MyBuddyCallback())
-    buddy.subscribe()
+        virtual void onBuddyState();
+    };
 
-  except pjsua.Error, err:
-    print 'Error adding buddy:', err
+In its subclass, application can implement the buddy callback to get the notifications on buddy state change.
 
-For more information please see ​Buddy class and ​BuddyCallback class reference documentation.
+Subscribing to Buddy's Presence Status
+---------------------------------------
+To subscribe to buddy's presence status, you need to add a buddy object and subscribe to buddy's presence status. The snippet below shows a sample code to achieve these:
+
+.. code-block:: c++
+
+    BuddyConfig cfg;
+    cfg.uri = "sip:alice@example.com";
+    MyBuddy buddy;
+    try {
+        buddy.create(*acc, cfg);
+        buddy.subscribePresence(true);
+    } catch(Error& err) {
+    }
+
+Then you can get the buddy's presence state change inside the onBuddyState() callback:
+
+.. code-block:: c++
+
+    void MyBuddy::onBuddyState()
+    {
+        BuddyInfo bi = getInfo();
+        cout << "Buddy " << bi.uri << " is " << bi.presStatus.statusText << endl;
+    }
+
+For more information, please see Buddy class reference documentation.
 
 Responding to Presence Subscription Request
-
+-------------------------------------------
 By default, incoming presence subscription to an account will be accepted automatically. You will probably want to change this behavior, for example only to automatically accept subscription if it comes from one of the buddy in the buddy list, and for anything else prompt the user if he/she wants to accept the request.
 
-This can be done by implementing the ​on_incoming_subscribe() method of the ​AccountCallback class.
+This can be done by overriding the onIncomingSubscribe() method of the Account class. Please see the documentation of this method for more info.
 
 Changing Account's Presence Status
+----------------------------------
+To change account's presence status, you can use the function Account.setOnlineStatus() to set basic account's presence status (i.e. available or not available) and optionally, some extended information (e.g. busy, away, on the phone, etc), such as:
 
-The ​Account class provides two methods to change account's presence status:
+.. code-block:: c++
 
-​set_basic_status() can be used to set basic account's presence status (i.e. available or not available).
-​set_presence_status() can be used to set both the basic presence status and some extended information (e.g. busy, away, on the phone, etc.).
-When the presence status is changed, the account will publish the new status to all of its presence subscriber, either with PUBLISH request or SUBSCRIBE request, or both, depending on account configuration.
+    try {
+        PresenceStatus ps;
+        ps.status = PJSUA_BUDDY_STATUS_ONLINE;
+        // Optional, set the activity and some note
+        ps.activity = PJRPID_ACTIVITY_BUSY;
+        ps.note = "On the phone";
+        acc->setOnlineStatus(ps);
+    } catch(Error& err) {
+    }
 
+When the presence status is changed, the account will publish the new status to all of its presence subscriber, either with PUBLISH request or NOTIFY request, or both, depending on account configuration.
+
+Instant Messaging(IM)
+---------------------
+You can send IM using Buddy.sendInstantMessage(). The transmission status of outgoing instant messages is reported in Account.onInstantMessageStatus() callback method of Account class.
+
+In addition to sending instant messages, you can also send typing indication to remote buddy using Buddy.sendTypingIndication().
+
+Incoming IM and typing indication received not within the scope of a call will be reported in the callback functions Account.onInstantMessage() and Account.onTypingIndication().
+
+Alternatively, you can send IM and typing indication within a call by using Call.sendInstantMessage() and Call.sendTypingIndication(). For more information, please see Call documentation.
+
+
+Class Reference
+---------------
+Buddy
++++++
+.. doxygenclass:: pj::Buddy
+        :path: xml
+        :members:
+
+Status
+++++++
+.. doxygenstruct:: pj::PresenceStatus
+        :path: xml
+        
+Info
+++++
+.. doxygenstruct:: pj::BuddyInfo
+        :path: xml
+
+Config
+++++++
+.. doxygenstruct:: pj::BuddyConfig
+        :path: xml
+
+

pjproject/trunk/doc/pjsip-book/reference.rst

@@ -1 @@
-
 
 PJSUA2 API Reference Manuals

pjproject/trunk/doc/pjsip-book/samples.rst

@@ -1 @@
-
 
 PJSUA2 Sample Applications
@@ -7 +6 @@
 ===========
 
+C++
+-----
+There is a very simple C++ sample application available in ``pjsip-apps/src/samples/pjsua2_demo.cpp``. The binary will be located in ``pjsip-apps/bin/samples``.
+
+
 Python GUI
 ------------------
-It requires Python 2.7 and above.
+This is a rather complete Python GUI sample apps, located in ``pjsip-apps/src/pygui``. It requires Python 2.7 and above, and the Python SWIG module of course. To use the application, simply run::
 
-Android & Java
------------------------------
+    python application.py
 
-C++
------------------------------
+Android
+----------------
+Please see https://trac.pjsip.org/repos/wiki/Getting-Started/Android#pjsua2 for Android sample application.
+
+Java
+----------------
+There is a Hello World type of application located in ``pjsip-apps/src/swig/java``. This requires the Java SWIG module. After building the SWIG module, run ``make test`` from this directory to run the app.
+
 
 Miscellaneous
 ===================
 
-How to dump call stats
+How to 
 -----------------------------
 
-How to 

------------------------------
-