More re #1715: doxygen integration into the book

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@4762 74dad513-b988-da41-8d7b-12977e46ad98

18 files changed, 1673 insertions, 971 deletions

diff --git a/doc/pjsip-book/Doxyfile b/doc/pjsip-book/Doxyfile
index 953d1151..49b794c2 100644
--- a/doc/pjsip-book/Doxyfile
+++ b/doc/pjsip-book/Doxyfile
@@ -648,7 +648,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # 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
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/pjsip-book/Makefile b/doc/pjsip-book/Makefile
index 17db6a6b..9f5bc222 100644
--- a/doc/pjsip-book/Makefile
+++ b/doc/pjsip-book/Makefile
@@ -45,7 +45,7 @@ clean:
 	-rm -rf xml
 	-rm -rf html
 
-xml:	Doxyfile
+xml:	Doxyfile ../../pjsip/include/pjsua2
 	doxygen
 
 html: xml
diff --git a/doc/pjsip-book/account.rst b/doc/pjsip-book/account.rst
index bee82db4..c4bfbaca 100644
--- a/doc/pjsip-book/account.rst
+++ b/doc/pjsip-book/account.rst
@@ -1,132 +1,222 @@
 
-

-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.

-

-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.

-

-Subclassing the Account class

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

-To use the Account class, normally application SHOULD create its own subclass, such as::

-

-    class MyAccount : public Account

-    {

-    public:

-        MyAccount() {}

-        ~MyAccount() {}

-

-        virtual void onRegState(OnRegStateParam &prm)

-        {

-            AccountInfo ai = getInfo();

-            cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=")

-                 << prm.code << endl;

-

-        }

-    

-        virtual void onIncomingCall(OnIncomingCallParam &iprm)

-        {

-            Call *call = new MyCall(*this, iprm.callId);

-            // Delete the call, which will also hangup the call

-            delete call;

-        }

-    };

-

-In its subclass, application can implement the account callbacks, which is basically used to process events related to the account, such as:

-

-- the status of SIP registration

-- incoming calls

-- incoming presence subscription requests

-- incoming instant message not from buddy

-

-Application needs to override the relevant callback methods in the derived class to handle these particular events.

-

-If the events are not handled, default actions will be invoked:

-

-- incoming calls will not be handled

-- incoming presence subscription requests will be accepted

-- incoming instant messages from non-buddy will be ignored

-

-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::

-

-    AccountConfig acc_cfg;

-    acc_cfg.sipConfig.transportId = tid;

-    MyAccount *acc = new MyAccount;

-    try {

-        acc->create(acc_cfg);

-    } catch(Error& err) {

-        cout << "Account creation error: " << err.reason << 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::

-

-    AccountConfig acc_cfg;

-    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;

-    }

-

-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;

-    }

-

-Account Configurations

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

-There are many more settings that can be specified in ​AccountConfig, like:

-

-- AccountRegConfig, to specify registration settings, such as registrar server and retry interval.

-- AccountSipConfig, to specify SIP settings, such as credential information and proxy server.

-- AccountCallConfig, to specify call settings, such as whether reliable provisional response (SIP 100rel) is required.

-- AccountPresConfig, to specify presence settings, such as whether presence publication (PUBLISH) is enabled.

-- AccountMwiConfig, to specify MWI (Message Waiting Indication) settings.

-- AccountNatConfig, to specify NAT settings, such as whether STUN or ICE is used.

-- AccountMediaConfig, to specify media settings, such as Secure RTP (SRTP) related settings.

-- AccountVideoConfig, to specify video settings, such as default capture and render device.

-

-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.

-

-

+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, 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 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, in order to receive notifications for the account. For example:
+
+.. code-block:: c++
+
+    class MyAccount : public Account
+    {
+    public:
+        MyAccount() {}
+        ~MyAccount() {}
+
+        virtual void onRegState(OnRegStateParam &prm)
+        {
+            AccountInfo ai = getInfo();
+            cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=")
+                 << prm.code << endl;
+        }
+    
+        virtual void onIncomingCall(OnIncomingCallParam &iprm)
+        {
+            Call *call = new MyCall(*this, iprm.callId);
+
+            // Just hangup for now
+            CallOpParam op;
+            op.statusCode = PJSIP_SC_DECLINE;
+            call->hangup(op);
+            
+            // And delete the call
+            delete call;
+        }
+    };
+
+In its subclass, application can implement the account callbacks, which is basically used to process events related to the account, such as:
+
+- the status of SIP registration
+- incoming calls
+- incoming presence subscription requests
+- incoming instant message not from buddy
+
+Application needs to override the relevant callback methods in the derived class to handle these particular events.
+
+If the events are not handled, default actions will be invoked:
+
+- incoming calls will not be handled
+- incoming presence subscription requests will be accepted
+- incoming instant messages from non-buddy will be ignored
+
+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. 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.idUri = "sip:test1@pjsip.org";
+
+    MyAccount *acc = new MyAccount;
+    try {
+        acc->create(acc_cfg);
+    } catch(Error& err) {
+        cout << "Account creation error: " << err.info() << 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:
+
+.. 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.info() << endl;
+    }
+
+Account Configurations
+-----------------------
+There are many more settings that can be specified in AccountConfig, like:
+
+- AccountRegConfig, to specify registration settings, such as registrar server and retry interval.
+- AccountSipConfig, to specify SIP settings, such as credential information and proxy server.
+- AccountCallConfig, to specify call settings, such as whether reliable provisional response (SIP 100rel) is required.
+- AccountPresConfig, to specify presence settings, such as whether presence publication (PUBLISH) is enabled.
+- AccountMwiConfig, to specify MWI (Message Waiting Indication) settings.
+- AccountNatConfig, to specify NAT settings, such as whether STUN or ICE is used.
+- AccountMediaConfig, to specify media settings, such as Secure RTP (SRTP) related settings.
+- AccountVideoConfig, to specify video settings, such as default capture and render device.
+
+Please see AccountConfig reference documentation for more info.
+
+Account Operations
+--------------------------------------
+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:
+
diff --git a/doc/pjsip-book/call.rst b/doc/pjsip-book/call.rst
index afb18cd7..f3aee4ee 100644
--- a/doc/pjsip-book/call.rst
+++ b/doc/pjsip-book/call.rst
@@ -1,103 +1,244 @@
 
-

-Calls

-=====

-Calls are represented by ​Call class.

-

-Subclassing the Call Class

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

-To use the Call class, normally application SHOULD create its own subclass, such as::

-

-    class MyCall : public Call

-    {

-    public:

-        MyCall(Account &acc, int call_id = PJSUA_INVALID_ID)

-        : Call(acc, call_id)

-        { }

-

-        ~MyCall()

-        { }

-

-        // Notification when call's state has changed.

-        virtual void onCallState(OnCallStateParam &prm);

-

-        // Notification when call's media state has changed.

-        virtual void onCallMediaState(OnCallMediaStateParam &prm);

-    };

-

-In its subclass, application can implement the call callbacks, which is basically used to process events related to the call, such as call state change or incoming call transfer request.

-

-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::

-

-    Call *call = new MyCall(*acc);

-    CallOpParam prm(true); // Use default call settings

-    try {

-        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.

-

-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::

-

-    void MyAccount::onIncomingCall(OnIncomingCallParam &iprm)

-    {

-        Call *call = new MyCall(*this, iprm.callId);

-        CallOpParam prm;

-        prm.statusCode = (pjsip_status_code)200;

-        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).

-

-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

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

-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::

-

-    void MyCall::onCallState(OnCallStateParam &prm)

-    {

-        CallInfo ci = getInfo();

-        if (ci.state == PJSIP_INV_STATE_DISCONNECTED) {

-            /* Delete the call */

-            delete this;

-        }

-    }

-

-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::

-

-    void MyCall::onCallMediaState(OnCallMediaStateParam &prm)

-    {

-        CallInfo ci = getInfo();

-        // Iterate all medias

-        for (unsigned i = 0; i < ci.media.size(); i++) {

-            if (getMedia(i)) { // Check if the media is valid

-                AudioMedia *aud_med = getMedia(i);

-                // Connect the call audio media to sound device

-                aud_med->startTransmit();

-                ->startTransmit(*aud_med);

-            }

-        }

-    }

-

-When the audio media becomes inactive (for example when the call is put on hold), there is no need to stop the audio media's transmission to/from the sound device since the call's audio media will be removed automatically from the conference bridge when it's no longer valid, and this will automatically remove all connections to/from the call.

-

-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.

-

+Calls
+=====
+Calls are represented by Call class.
+
+Subclassing the Call Class
+------------------------------------
+To use the Call class, normally application SHOULD create its own subclass, such as:
+
+.. code-block:: c++
+
+    class MyCall : public Call
+    {
+    public:
+        MyCall(Account &acc, int call_id = PJSUA_INVALID_ID)
+        : Call(acc, call_id)
+        { }
+
+        ~MyCall()
+        { }
+
+        // Notification when call's state has changed.
+        virtual void onCallState(OnCallStateParam &prm);
+
+        // Notification when call's media state has changed.
+        virtual void onCallMediaState(OnCallMediaStateParam &prm);
+    };
+
+In its subclass, application can implement the call callbacks, which is basically used to process events related to the call, such as call state change or incoming call transfer request.
+
+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 dest_uri, you can initiate outgoing call with the snippet below:
+
+.. code-block:: c++
+
+    Call *call = new MyCall(*acc);
+    CallOpParam prm(true); // Use default call settings
+    try {
+        call->makeCall(dest_uri, prm);
+    } catch(Error& err) {
+        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:
+
+.. code-block:: c++
+
+    void MyAccount::onIncomingCall(OnIncomingCallParam &iprm)
+    {
+        Call *call = new MyCall(*this, iprm.callId);
+        CallOpParam prm;
+        prm.statusCode = PJSIP_SC_OK;
+        call->answer(prm);
+    }
+
+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
+-------------------
+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:
+
+.. code-block:: c++
+
+    void MyCall::onCallState(OnCallStateParam &prm)
+    {
+        CallInfo ci = getInfo();
+        if (ci.state == PJSIP_INV_STATE_DISCONNECTED) {
+            /* Delete the call */
+            delete this;
+        }
+    }
+
+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 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 the call medias
+        for (unsigned i = 0; i < ci.media.size(); 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
+                AudDevManager& mgr = Endpoint::instance().audDevManager();
+                aud_med->startTransmit(mgr.getPlaybackDevMedia());
+                mgr.getCaptureDevMedia().startTransmit(*aud_med);
+            }
+        }
+    }
+
+When the audio media becomes inactive (for example when the call is put on hold), there is no need to stop the audio media's transmission to/from the sound device since the call's audio media will be removed automatically from the conference bridge when it's no longer valid, and this will automatically remove all connections to/from the call.
+
+Call Operations
+-------------------
+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
+
+
diff --git a/doc/pjsip-book/consider.rst b/doc/pjsip-book/consider.rst
index 5d466707..17dc2150 100644
--- a/doc/pjsip-book/consider.rst
+++ b/doc/pjsip-book/consider.rst
@@ -1,187 +1,214 @@
 
-

-

-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.

-

-Windows Desktop

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

-Windows is supported from Windows 2000 up to the recent Windows 8 and beyond. All features are expected to work. 64bit support was added recently. Development is based on Visual Studio. Considerations for this platform include:

-

-#. because Visual Studio file format keeps changing on every release, we decided to support the lowest denominator, namely Visual Studio 2005. Unfortunately the project upgrade procedure fails on Visual Studio 2010, and we don't have any solution for that. But VS 2008 and VS 20012 work.

-

-MacOS X

--------

-All features are expected to work. Considerations include:

-

-#. development with XCode is currently not supported. This is **not** to say that you cannot use XCode, but PJSIP only provides basic Makefiles and if you want to use XCode you'd need to arrange the project yourself.

-#. Mac systems typically provides very good sound device, so we don't expect any problems with audio on Mac. 

-

-Linux Desktop

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

-All features are expected to work. Linux considerations:

-

-#. use our native ALSA backend instead of PortAudio because ALSA has less jitter than OSS and our backend is more lightweight than PortAudio

-

-

-iOS for iPhone, iPad, and iPod Touch

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

-All features except video are expected to work (video is coming soon!). Considerations for iOS:

-

-#. you need to use TCP transport for SIP for the background feature to work

-#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange

-#. there are some specific issues for iOS 7 and beyond, please see http://trac.pjsip.org/repos/ticket/1697

-#. if SSL is needed, you need to compile OpenSSL for iOS

-

-

-Android

--------

-All features except video are expected to work (video is coming soon!). Considerations for Android:

-

-#. you can only use pjsua2 Java binding for this target

-#. it has been reported that Android audio device is not so good in general, so some audio tuning may be needed. Echo cancellation also needs to be checked

-#. this is also a new platform for us 

-

-

-Symbian

--------

-Symbian has been supported for a long time but it doesn't get too many attention recently. In general all features (excluding video) are expected to work, but we're not going to do Symbian specific development anymore. Other considerations for Symbian:

-

-#. the MDA audio is not very good (it has high latency), so normally you'd want to use Audio Proxy Server (APS) or VoIP Audio Service (VAS) for the audio device, which we support. Using these audio backends will also provide us with high quality echo cancellation as well as low bitrate codecs such as AMR-NB, G.729, and iLBC. But VAS and APS requires purchase of Nokia development certificate to sign the app, and also since APS and VAS only run on specific device type, you need to package the app carefully and manage the deployment to cover various device types.

-

-

-Blackberry 10

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

-Blackberry 10 is supported since PJSIP version 2.2. As this is a relatively new platform for us, we are currently listening to developer's feedback regarding the port. But so far it seems to be working well. Some considerations for BB10 platform include:

-

-#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange

-

-

-Windows Mobile

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

-This is the old Windows Mobile platform that is based on WinCE. This platform has been supported for a long time, but doesn't seem to attract any attentions recently. We expect all features except video to work, but there may be some errors every now and then because this target is not actively maintained. No new development will be done for this platform.

-

-Other considerations for Windows Mobile platform are:

-

-#. the quality of audio device on WM varies a lot, and this affects audio latency. Audio latency could go as high as hundreds of millisecond on bad hardware.

-#. echo cancellation could be a problem. We can only use basic echo suppressor due to hardware limitation, and combined with bad quality of audio device, it may cause ineffective echo cancellation. This could be mitigated by setting the audio level to low.

-

-

-Windows Phone 8

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

-Windows Phone 8 (WP8) support is being added to PJSIP version 2.2 and is still under development. Specific considerations for this platform are:

-

-#. WP8 governs specific interaction with WP8 GUI and framework that needs to be followed by application in order to make VoIP call work seamlessly on the device. Some lightweight process will be created by WP8 framework in order for background call to work and PJSIP needs to put it's background processing in this process's context. Currently this feature is under development.

-

-

-

-Embedded Linux

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

-In general embedded Linux support is similar to Linux and we find no problems with it. We found some specific considerations for embedded Linux as follows:

-

-#. the performance of the audio device is probably the one with most issues, as some development boards have not so descent sound device that has high audio jitter (or burst) and latency. This will affect end to end audio latency and also the performance of the echo canceller. Also we found that ALSA generally works better than OSS, so if you can have ALSA up and running that will be better. Use our native ALSA backend audio device instead of PortAudio since it is simpler and lighter.

-

-

-QNX or Other Posix Embedded OS

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

-This is not part of our officially supported OSes, but users have run PJSIP on QNX and Blackberry 10 is based on QNX too. Since QNX provides Posix API, and maybe by using the settings found in the configure-bb10 script, PJSIP should be able to run on it, but you need to develop PJMEDIA sound device wrapper for your audio device. Other than this, we don't have enough experience to comment on the platform. 

-

-

-Other Unix Desktop OSes

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

-Community members, including myself, have occasionally run PJSIP on other Unix OSes such as Solaris, FreeBSD, and OpenBSD. We expect PJSIP to run on these platforms (maybe with a little kick).

-

-

-Porting to Other Embedded OSes

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

-It is possible to port PJSIP to other embedded OSes or even directly to device without OS and people have done so. In general, the closer resemblance the new OS to existing supported OS, the easier the porting job will be. The good thing is, PJSIP has been made to be very very portable, and system dependent features are localized in PJLIB and PJMEDIA audio device, so the effort is more quantifiable. Once you are able to successfully run *pjlib-test*, you are more or less there with your porting effort. Other than that, if you really want to port PJSIP to new platform, you probably already know what you're doing. 

-

-

-

-Which API to Use

-================

-

-PJSIP, PJMEDIA, and PJNATH Level

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

-At the lowest level we have the individual PJSIP **C** libraries, which consist of PJSIP, PJMEDIA, and PJNATH, with PJLIB-UTIL and PJLIB as support libraries. This level provides the most flexibility, but it's also the hardest to use. The only reason you'd want to use this level is if:

-

-#. you only need the individual library (say, PJNATH)

-#. you need to be very very tight in footprint (say when things need to be measured in Kilobytes instead of Megabytes)

-#. you are **not** developing a SIP client

-

-Use the corresponding PJSIP, PJMEDIA, PJNATH manuals from http://trac.pjsip.org/repos/ for information on how to use the libraries. If you use PJSIP, the PJSIP Developer's Guide (PDF) from that page provides in-depth information about PJSIP library.  

-

-PJSUA-LIB API

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

-Next up is PJSUA-LIB API that combines all those libraries into a high level, integrated client user agent library written in C. This is the library that most PJSIP users use, and the highest level abstraction before pjsua2 was created. 

-

-Motivations for using PJSUA-LIB library includes:

-

-#. developing client application (PJSUA-LIB is optimized for developing client app)

-#. better efficiency than higher level API

-

-

-pjsua2 C++ API

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

-pjsua2 is a new, objected oriented, C++ API created on top of PJSUA-LIB. The API is different than PJSUA-LIB, but it should be even easier to use and it should have better documentation too (such as this book). The pjsua2 API removes most cruxes typically associated with PJSIP, such as the pool and pj_str_t, and add new features such as object persistence so you can save your configs to a file, for example. All data structures are rewritten for more clarity. 

-

-A C++ application can use pjsua2 natively, while at the same time still has access to the lower level objects if it needs to. This means that the C++ application should not loose any information from using the C++ abstraction, compared to if it is using PJSUA-LIB directly. The C++ application also should not loose the ability to extend the library. It would still be able to register a custom PJSIP module, pjmedia_port, pjmedia_transport, and so on.

-

-Benefits of using pjsua2 C++ API include:

-

-#. cleaner object oriented API

-#. uniform API for higher level language such as Java and Python

-#. persistence API

-#. the ability to access PJSUA-LIB and lower level libraries when needed (including the ability to extend the libraries, for example creating custom PJSIP module, pjmedia_port, pjmedia_transport, etc.)

-

-

-Some considerations on pjsua2 C++ API are:

-#. instead of returning error, the API uses exception for error reporting

-#. pjsua2 uses standard C++ library

-#. the performance penalty due to the API abstraction should be negligible on typical modern device

-

-

-

-pjsua2 API for Java, Python, and Others

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

-The pjsua2 API is also available for non-native code via SWIG binding. Configurations for Java and Python are provided with the distribution. Thanks to SWIG, other language bindings may be generated relatively easily.

- 

-The pjsua2 API for non-native code is effectively the same as pjsua2 C++ API. However, unlike C++, you cannot access PJSUA-LIB and the underlying C libraries from the scripting language, hence you are limited to what pjsua2 provides.

-

-You can use this API if native application development is not available in target platform (such as Android), or if you prefer to develop with non-native code instead of C/C++.

-

-

-

-

-Network and Infrastructure Considerations

-=========================================

-

-NAT Issues

-----------

-

-

-TCP Requirement

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

-If you support iOS devices in your service, you need to use TCP, because only TCP will work on iOS device when it is in background mode. This means your infrastructure needs to support TCP. 

-

-

-Sound Device

-============

-

-Latency

--------

-

-

-Echo Cancellation

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

-

-

-

-

+
+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
+---------------
+Windows is supported from Windows 2000 up to the recent Windows 8 and beyond. All features are expected to work. 64bit support was added recently. Development is based on Visual Studio. Considerations for this platform include:
+
+#. because Visual Studio file format keeps changing on every release, we decided to support the lowest denominator, namely Visual Studio 2005. Unfortunately the project upgrade procedure fails on Visual Studio 2010, and we don't have any solution for that. But VS 2008 and VS 20012 work.
+
+MacOS X
+-------
+All features are expected to work. Considerations include:
+
+#. development with XCode is currently not supported. This is **not** to say that you cannot use XCode, but PJSIP only provides basic Makefiles and if you want to use XCode you'd need to arrange the project yourself.
+#. Mac systems typically provides very good sound device, so we don't expect any problems with audio on Mac. 
+
+Linux Desktop
+-------------
+All features are expected to work. Linux considerations:
+
+#. use our native ALSA backend instead of PortAudio because ALSA has less jitter than OSS and our backend is more lightweight than PortAudio
+
+
+iOS for iPhone, iPad, and iPod Touch
+------------------------------------
+All features except video are expected to work (video is coming soon!). Considerations for iOS:
+
+#. you need to use TCP transport for SIP for the background feature to work
+#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange
+#. there are some specific issues for iOS 7 and beyond, please see http://trac.pjsip.org/repos/ticket/1697
+#. if SSL is needed, you need to compile OpenSSL for iOS
+
+
+Android
+-------
+All features except video are expected to work (video is coming soon!). Considerations for Android:
+
+#. you can only use pjsua2 Java binding for this target
+#. it has been reported that Android audio device is not so good in general, so some audio tuning may be needed. Echo cancellation also needs to be checked
+#. this is also a new platform for us 
+
+
+Symbian
+-------
+Symbian has been supported for a long time but it doesn't get too many attention recently. In general all features (excluding video) are expected to work, but we're not going to do Symbian specific development anymore. Other considerations for Symbian:
+
+#. the MDA audio is not very good (it has high latency), so normally you'd want to use Audio Proxy Server (APS) or VoIP Audio Service (VAS) for the audio device, which we support. Using these audio backends will also provide us with high quality echo cancellation as well as low bitrate codecs such as AMR-NB, G.729, and iLBC. But VAS and APS requires purchase of Nokia development certificate to sign the app, and also since APS and VAS only run on specific device type, you need to package the app carefully and manage the deployment to cover various device types.
+
+
+Blackberry 10
+-------------
+Blackberry 10 is supported since PJSIP version 2.2. As this is a relatively new platform for us, we are currently listening to developer's feedback regarding the port. But so far it seems to be working well. Some considerations for BB10 platform include:
+
+#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange
+
+
+Windows Mobile
+--------------
+This is the old Windows Mobile platform that is based on WinCE. This platform has been supported for a long time, but doesn't seem to attract any attentions recently. We expect all features except video to work, but there may be some errors every now and then because this target is not actively maintained. No new development will be done for this platform.
+
+Other considerations for Windows Mobile platform are:
+
+#. the quality of audio device on WM varies a lot, and this affects audio latency. Audio latency could go as high as hundreds of millisecond on bad hardware.
+#. echo cancellation could be a problem. We can only use basic echo suppressor due to hardware limitation, and combined with bad quality of audio device, it may cause ineffective echo cancellation. This could be mitigated by setting the audio level to low.
+
+
+Windows Phone 8
+---------------
+Windows Phone 8 (WP8) support is being added to PJSIP version 2.2 and is still under development. Specific considerations for this platform are:
+
+#. WP8 governs specific interaction with WP8 GUI and framework that needs to be followed by application in order to make VoIP call work seamlessly on the device. Some lightweight process will be created by WP8 framework in order for background call to work and PJSIP needs to put it's background processing in this process's context. Currently this feature is under development.
+
+
+
+Embedded Linux
+--------------
+In general embedded Linux support is similar to Linux and we find no problems with it. We found some specific considerations for embedded Linux as follows:
+
+#. the performance of the audio device is probably the one with most issues, as some development boards have not so descent sound device that has high audio jitter (or burst) and latency. This will affect end to end audio latency and also the performance of the echo canceller. Also we found that ALSA generally works better than OSS, so if you can have ALSA up and running that will be better. Use our native ALSA backend audio device instead of PortAudio since it is simpler and lighter.
+
+
+QNX or Other Posix Embedded OS
+------------------------------
+This is not part of our officially supported OSes, but users have run PJSIP on QNX and Blackberry 10 is based on QNX too. Since QNX provides Posix API, and maybe by using the settings found in the configure-bb10 script, PJSIP should be able to run on it, but you need to develop PJMEDIA sound device wrapper for your audio device. Other than this, we don't have enough experience to comment on the platform. 
+
+
+Other Unix Desktop OSes
+-----------------------
+Community members, including myself, have occasionally run PJSIP on other Unix OSes such as Solaris, FreeBSD, and OpenBSD. We expect PJSIP to run on these platforms (maybe with a little kick).
+
+
+Porting to Other Embedded OSes
+------------------------------
+It is possible to port PJSIP to other embedded OSes or even directly to device without OS and people have done so. In general, the closer resemblance the new OS to existing supported OS, the easier the porting job will be. The good thing is, PJSIP has been made to be very very portable, and system dependent features are localized in PJLIB and PJMEDIA audio device, so the effort is more quantifiable. Once you are able to successfully run *pjlib-test*, you are more or less there with your porting effort. Other than that, if you really want to port PJSIP to new platform, you probably already know what you're doing. 
+
+
+
+Which API to Use
+================
+
+PJSIP, PJMEDIA, and PJNATH Level
+--------------------------------
+At the lowest level we have the individual PJSIP **C** libraries, which consist of PJSIP, PJMEDIA, and PJNATH, with PJLIB-UTIL and PJLIB as support libraries. This level provides the most flexibility, but it's also the hardest to use. The only reason you'd want to use this level is if:
+
+#. you only need the individual library (say, PJNATH)
+#. you need to be very very tight in footprint (say when things need to be measured in Kilobytes instead of Megabytes)
+#. you are **not** developing a SIP client
+
+Use the corresponding PJSIP, PJMEDIA, PJNATH manuals from http://trac.pjsip.org/repos/ for information on how to use the libraries. If you use PJSIP, the PJSIP Developer's Guide (PDF) from that page provides in-depth information about PJSIP library.  
+
+PJSUA-LIB API
+-------------
+Next up is PJSUA-LIB API that combines all those libraries into a high level, integrated client user agent library written in C. This is the library that most PJSIP users use, and the highest level abstraction before pjsua2 was created. 
+
+Motivations for using PJSUA-LIB library includes:
+
+#. developing client application (PJSUA-LIB is optimized for developing client app)
+#. better efficiency than higher level API
+
+
+pjsua2 C++ API
+--------------
+pjsua2 is a new, objected oriented, C++ API created on top of PJSUA-LIB. The API is different than PJSUA-LIB, but it should be even easier to use and it should have better documentation too (such as this book). The pjsua2 API removes most cruxes typically associated with PJSIP, such as the pool and pj_str_t, and add new features such as object persistence so you can save your configs to a file, for example. All data structures are rewritten for more clarity. 
+
+A C++ application can use pjsua2 natively, while at the same time still has access to the lower level objects if it needs to. This means that the C++ application should not loose any information from using the C++ abstraction, compared to if it is using PJSUA-LIB directly. The C++ application also should not loose the ability to extend the library. It would still be able to register a custom PJSIP module, pjmedia_port, pjmedia_transport, and so on.
+
+Benefits of using pjsua2 C++ API include:
+
+#. cleaner object oriented API
+#. uniform API for higher level language such as Java and Python
+#. persistence API
+#. the ability to access PJSUA-LIB and lower level libraries when needed (including the ability to extend the libraries, for example creating custom PJSIP module, pjmedia_port, pjmedia_transport, etc.)
+
+
+Some considerations on pjsua2 C++ API are:
+#. instead of returning error, the API uses exception for error reporting
+#. pjsua2 uses standard C++ library
+#. the performance penalty due to the API abstraction should be negligible on typical modern device
+
+
+
+pjsua2 API for Java, Python, and Others
+---------------------------------------
+The pjsua2 API is also available for non-native code via SWIG binding. Configurations for Java and Python are provided with the distribution. Thanks to SWIG, other language bindings may be generated relatively easily.
+ 
+The pjsua2 API for non-native code is effectively the same as pjsua2 C++ API. However, unlike C++, you cannot access PJSUA-LIB and the underlying C libraries from the scripting language, hence you are limited to what pjsua2 provides.
+
+You can use this API if native application development is not available in target platform (such as Android), or if you prefer to develop with non-native code instead of C/C++.
+
+
+
+
+Network and Infrastructure Considerations
+=========================================
+
+NAT Issues
+----------
+
+
+TCP Requirement
+---------------
+If you support iOS devices in your service, you need to use TCP, because only TCP will work on iOS device when it is in background mode. This means your infrastructure needs to support TCP. 
+
+
+Sound Device
+============
+
+Latency
+-------
+
+
+Echo Cancellation
+-----------------
+
+
+
+
diff --git a/doc/pjsip-book/endpoint.rst b/doc/pjsip-book/endpoint.rst
index 1152307e..3dfefa21 100644
--- a/doc/pjsip-book/endpoint.rst
+++ b/doc/pjsip-book/endpoint.rst
@@ -1,96 +1,172 @@
 
-

-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:

-

-- 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.

-

-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 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.

-

-Instantiating the Endpoint

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

-Before anything else, you must instantiate the Endpoint class::

-

-    Endpoint *ep = new Endpoint;

-

-Once the endpoint is instantiated, you can retrieve the Endpoint instance using Endpoint.instance() static method.

-

-Creating the Library

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

-Create the library by calling its libCreate() method::

-

-    try {

-        ep->libCreate();

-    } catch(Error& err) {

-        cout << "Startup error: " << err.reason << endl;

-    }

-

-The libCreate() method will raise exception if error occurs, so we need to trap the exception using try/catch clause as above.

-

-Initializing the Library and Configuring the Settings

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

-

-The EpConfig class provides endpoint configuration which allows the customization of the following settings:

-

-- UAConfig, to specify core SIP user agent settings.

-- MediaConfig, to specify various media settings, including ICE and TURN.

-- 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::

-

-    EpConfig ep_cfg;

-    ep_cfg.logConfig.level = 5;

-    ep_cfg.uaConfig.maxCalls = 4;

-    ep_cfg.mediaConfig.sndClockRate = 16000;

-

-Next, you can initialize the library by calling libInit()::

-

-    try {

-        EpConfig ep_cfg;

-        // Specify customization of settings in ep_cfg

-        ep->libInit(ep_cfg);

-    } catch(Error& err) {

-        cout << "Initialization error: " << err.reason << endl;

-    }

-

-The snippet above initializes the library with the default settings.

-

-Creating One or More Transports

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

-Application needs to create one or more ​transports before it can send or receive SIP messages::

-

-    try {

-        TransportConfig tcfg;

-        tcfg.port = 5060;

-        TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_UDP, tcfg);

-    } catch(Error& err) {

-        cout << "Transport creation error: " << err.reason << 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.

-

-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::

-

-    try {

-        ep->libStart();

-    } catch(Error& err) {

-        cout << "Startup error: " << err.reason << 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()::

-

-    delete ep;

-

+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, 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 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 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.
+
+Instantiating the Endpoint
+--------------------------
+Before anything else, you must instantiate the Endpoint class::
+
+    Endpoint *ep = new Endpoint;
+
+Once the endpoint is instantiated, you can retrieve the Endpoint instance using Endpoint.instance() static method.
+
+Creating the Library
+----------------------
+Create the library by calling its libCreate() method:
+
+.. code-block:: c++
+
+    try {
+        ep->libCreate();
+    } catch(Error& err) {
+        cout << "Startup error: " << err.info() << endl;
+    }
+
+The libCreate() method will raise exception if error occurs, so we need to trap the exception using try/catch clause as above.
+
+Initializing the Library and Configuring the Settings
+----------------------------------------------------------------------------
+
+The EpConfig class provides endpoint configuration which allows the customization of the following settings:
+
+- UAConfig, to specify core SIP user agent settings.
+- MediaConfig, to specify various media *global* settings
+- LogConfig, to customize logging settings.
+
+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;
+    ep_cfg.logConfig.level = 5;
+    ep_cfg.uaConfig.maxCalls = 4;
+    ep_cfg.mediaConfig.sndClockRate = 16000;
+
+Next, you can initialize the library by calling libInit():
+
+.. code-block:: c++
+
+    try {
+        EpConfig ep_cfg;
+        // Specify customization of settings in ep_cfg
+        ep->libInit(ep_cfg);
+    } catch(Error& err) {
+        cout << "Initialization error: " << err.info() << endl;
+    }
+
+The snippet above initializes the library with the default settings.
+
+Creating One or More Transports
+--------------------------------------------------
+Application needs to create one or more transports before it can send or receive SIP messages:
+
+.. code-block:: c++
+
+    try {
+        TransportConfig tcfg;
+        tcfg.port = 5060;
+        TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_UDP, tcfg);
+    } catch(Error& err) {
+        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.
+
+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:
+
+.. code-block:: c++
+
+    try {
+        ep->libStart();
+    } catch(Error& err) {
+        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. 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
+
diff --git a/doc/pjsip-book/fetch_trac.py b/doc/pjsip-book/fetch_trac.py
index 3c754624..94e59110 100644
--- a/doc/pjsip-book/fetch_trac.py
+++ b/doc/pjsip-book/fetch_trac.py
@@ -1,12 +1,16 @@
 import urllib2
 import sys
+import unicodedata
 
 def fetch_rst(url):
 	print 'Fetching %s..' % url
 	req = urllib2.Request(url)
 		
 	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("{{{")
 	if pos >= 0:
@@ -78,8 +82,10 @@ if __name__ == '__main__':
 	
 	pages = process_index('index')
 	for page in pages:
+		#if not 'endpoint' in page:
+		#	continue
 		url = url_format % (page)
 		fetch_rst(url)
 		
 	print 'Done.'
-	
\ No newline at end of file
+	
diff --git a/doc/pjsip-book/getting_started.rst b/doc/pjsip-book/getting_started.rst
new file mode 100644
index 00000000..88237639
--- /dev/null
+++ b/doc/pjsip-book/getting_started.rst
@@ -0,0 +1,211 @@
+Getting Started
+******************************
+
+Building PJSUA2
+======================
+The PJSUA2 C++ library will be built by default by PJSIP build system.
+
+Building Python and Java SWIG Modules
+======================================
+The 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.
+
+Requirements
+------------
+
+#. ``JDK``.
+#. ``Python``, version 2.7 or above is required.
+   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`_.
+
+.. _`ActivePython-2.7.5`: http://www.activestate.com/activepython/downloads
+.. _`ActiveState`: http://www.activestate.com
+
+Testing The Installation
+------------------------
+To test the installation, simply run python and import ``pjsua2`` module::
+
+  $ python
+  > import pjsua2
+  > ^Z
+
+
+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.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
+===========================
+The equivalence of the C++ sample code above in Python is as follows:
+
+.. code-block:: python
+
+  # Subclass to extend the Account and get notifications etc.
+  class Account(pj.Account):
+    def onRegState(self, prm):
+        print "***OnRegState: " + prm.reason
+
+  # pjsua2 test function
+  def pjsua2_test():
+    # Create and initialize the library
+    ep_cfg = pj.EpConfig()
+    ep = pj.Endpoint()
+    ep.libCreate()
+    ep.libInit(ep_cfg)
+    
+    # Create SIP transport. Error handling sample is shown
+    sipTpConfig = pj.TransportConfig();
+    sipTpConfig.port = 5060;
+    ep.transportCreate(pj.PJSIP_TRANSPORT_UDP, sipTpConfig);
+    # Start the library
+    ep.libStart();
+    
+    acfg = pj.AccountConfig();
+    acfg.idUri = "sip:test@pjsip.org";
+    acfg.regConfig.registrarUri = "sip:pjsip.org";
+    cred = pj.AuthCredInfo("digest", "*", "test", 0, "pwtest");
+    acfg.sipConfig.authCreds.append( cred );
+    # Create the account
+    acc = Account();
+    acc.create(acfg);
+    # Here we don't have anything else to do..
+    time.sleep(10);
+
+    # Destroy the library
+    ep.libDestroy()
+
+  #
+  # main()
+  #
+  if __name__ == "__main__":
+    pjsua2_test()
+
+
+Using in Java Application
+=========================
+The equivalence of the C++ sample code above in Java is as follows:
+
+.. code-block:: java
+
+  import org.pjsip.pjsua2.*;
+
+  // Subclass to extend the Account and get notifications etc.
+  class MyAccount extends Account {
+    @Override
+    public void onRegState(OnRegStateParam prm) {
+        System.out.println("*** On registration state: " + prm.getCode() + prm.getReason());
+    }
+  }
+
+  public class test {
+    static {
+        System.loadLibrary("pjsua2");
+        System.out.println("Library loaded");
+    }
+    
+    public static void main(String argv[]) {
+        try {
+            // Create endpoint
+            Endpoint ep = new Endpoint();
+            ep.libCreate();
+            // Initialize endpoint
+            EpConfig epConfig = new EpConfig();
+            ep.libInit( epConfig );
+            // Create SIP transport. Error handling sample is shown
+            TransportConfig sipTpConfig = new TransportConfig();
+            sipTpConfig.setPort(5060);
+            ep.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_UDP, sipTpConfig);
+            // Start the library
+            ep.libStart();
+
+            AccountConfig acfg = new AccountConfig();
+            acfg.setIdUri("sip:test@pjsip.org");
+            acfg.getRegConfig().setRegistrarUri("sip:pjsip.org");
+            AuthCredInfo cred = new AuthCredInfo("digest", "*", "test", 0, "secret");
+            acfg.getSipConfig().getAuthCreds().add( cred );
+            // Create the account
+            MyAccount acc = new MyAccount();
+            acc.create(acfg);
+            // Here we don't have anything else to do..
+            Thread.sleep(10000);
+            /* Explicitly delete the account.
+             * This is to avoid GC to delete the endpoint first before deleting
+             * the account.
+             */
+            acc.delete();
+            
+            // Explicitly destroy and delete endpoint
+            ep.libDestroy();
+            ep.delete();
+            
+        } catch (Exception e) {
+            System.out.println(e);
+            return;
+        }
+    }
+  }
+
+
diff --git a/doc/pjsip-book/index.rst b/doc/pjsip-book/index.rst
index 4ffce9ef..3cf4518a 100644
--- a/doc/pjsip-book/index.rst
+++ b/doc/pjsip-book/index.rst
@@ -1,36 +1,37 @@
+.. The PJSIP Book documentation master file, created by
+   sphinx-quickstart on Sat Nov 30 06:36:26 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+The PJSIP Book
+==========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :numbered: 1
+
+   intro
+   consider
+   intro_pjsua2
+   getting_started
+   endpoint
+   account
+   media
+   call
+   presence
+   samples
+   optimization
+   media_quality
+   network_problems
+   reference
+
+   
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 
-.. The PJSIP Book documentation master file, created by

-   sphinx-quickstart on Sat Nov 30 06:36:26 2013.

-   You can adapt this file completely to your liking, but it should at least

-   contain the root `toctree` directive.

-

-Welcome to The PJSIP Book's documentation!

-==========================================

-

-Contents:

-

-.. toctree::

-   :maxdepth: 2

-

-   intro

-   consider

-   intro_pjsua2

-   endpoint

-   account

-   media

-   call

-   presence

-   samples

-   optimization

-   media_quality

-   network_problems

-   reference

-

-   

-Indices and tables

-==================

-

-* :ref:`genindex`

-* :ref:`modindex`

-* :ref:`search`

-

diff --git a/doc/pjsip-book/intro.rst b/doc/pjsip-book/intro.rst
index 69e63035..ce5c7d9b 100644
--- a/doc/pjsip-book/intro.rst
+++ b/doc/pjsip-book/intro.rst
@@ -1,33 +1,37 @@
 
-

-Introduction to PJSUA2

-*******************************

-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.

-

-Getting Started with PJSIP

-==============================

-To begin using PJSIP

-http://trac.pjsip.org/repos/wiki/Getting-Started

-

-PJSIP Info and Documentation

-================================

-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 - Reference Manual

-

-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 Language Binding Support

-===================================

-Optional if you want to:

-​SWIG (minimum version 2.0.5)

-

+Introduction to PJSUA2
+*******************************
+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 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
+==============================
+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
+================================
+To get other relevant info and documentations about PJSIP, you can visit:
+
+- `PJSIP General Wiki`_
+- `PJSIP FAQ`_
+- `PJSIP Reference Manual`_ - please see Reference Manual section
+
+.. _`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 ``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
+===================================
+The PJSUA2 API is also available for other programming languages via SWIG binding, such as Java and Python.
+
diff --git a/doc/pjsip-book/intro_pjsua2.rst b/doc/pjsip-book/intro_pjsua2.rst
index d3430f20..747badb2 100644
--- a/doc/pjsip-book/intro_pjsua2.rst
+++ b/doc/pjsip-book/intro_pjsua2.rst
@@ -1,158 +1,101 @@
+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 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.
+
+
+PJSUA2 Main Classes
+======================
+Here are the main classes of the PJSUA2:
+
+Endpoint
+--------------
+This 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.
+
+Account
+-------------
+An 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.
+
+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 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
+---------
+This 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.
+
+General Concepts
+==================
+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.
+
+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 ([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. Heres an example to save a config to a file:
+
+.. code-block:: c++
+
+    EpConfig epCfg;
+    JsonDocument jDoc;
+    epCfg.uaConfig.maxCalls = 61;
+    epCfg.uaConfig.userAgent = "Just JSON Test";
+    jDoc.writeObject(epCfg);
+    jDoc.saveFile("jsontest.js");
+
+To load from the file:
+
+.. code-block:: c++
+
+    EpConfig epCfg;
+    JsonDocument jDoc;
+    jDoc.loadFile("jsontest.js");
+    jDoc.readObject(epCfg);
+
 
-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 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.

-

-

-PJSUA2 Main Classes

-======================

-Here are the main classes of the PJSUA2:

-

-Endpoint

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

-This 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.

-

-Account

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

-An 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.

-

-Media

-----------

-This class represents a media element which is capable to either produce media or takes media.

-

-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.

-

-Buddy

----------

-This 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.

-

-General Concepts

-==================

-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.

-

-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.

-

-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:

-

-.. code-block:: c++

-

-    EpConfig epCfg;

-    JsonDocument jDoc;

-    epCfg.uaConfig.maxCalls = 61;

-    epCfg.uaConfig.userAgent = "Just JSON Test";

-    jDoc.writeObject(epCfg);

-    jDoc.saveFile(“jsontest.js”);

-

-To load from the file:

-

-.. code-block:: c++

-

-    EpConfig epCfg;

-    JsonDocument jDoc;

-    jDoc.loadFile("jsontest.js");

-    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

-=========================

-

-

-

-

diff --git a/doc/pjsip-book/media.rst b/doc/pjsip-book/media.rst
index 5dc4d1bf..35f2f4e4 100644
--- a/doc/pjsip-book/media.rst
+++ b/doc/pjsip-book/media.rst
@@ -1,113 +1,220 @@
 
-

-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).

-

-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.

-- AudioMediaPlayer, to play WAV file(s).

-- AudioMediaRecorder, to record audio to a WAV file.

-

-More media objects may be added in the future.

-

-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.

-

-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::

-

-    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) {

-    }

-

-Recording to WAV File

-+++++++++++++++++++++

-Or if you want to record the microphone to the WAV file, simply do this::

-

-    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.)

-

-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.

-

-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();

-

-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();

-

-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).

-

-Conference Call

-+++++++++++++++

-To enable both parties talk to each other, just establish bidirectional media between them::

-

-    aud_med->startTransmit(*aud_med2);

-    aud_med2->startTransmit(*aud_med);

-

-Now the three parties (us and both remote parties) will be able to talk to each other.

-

-Recording the Conference

-++++++++++++++++++++++++

-

-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);

-    aud_med->startTransmit(recorder);

-    aud_med2->startTransmit(recorder);

-

+Media
+=====
+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:
+
+- 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.
+
+More media objects may be added in the future.
+
+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. 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 sound device, just start the transmission of the WAV playback object to the sound device's playback media:
+
+.. code-block:: c++
+
+    AudioMediaPlayer player;
+    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 audio from the sound device to the WAV file, simply do this:
+
+.. code-block:: c++
+
+    AudioMediaRecorder recorder;
+    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 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 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:
+
+.. 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).
+
+Conference Call
++++++++++++++++
+To enable both parties talk to each other, just establish bidirectional media between them:
+
+.. code-block:: c++
+
+    aud_med->startTransmit(*aud_med2);
+    aud_med2->startTransmit(*aud_med);
+
+Now the three parties (us and both remote parties) will be able to talk to each other.
+
+Recording the Conference
+++++++++++++++++++++++++
+
+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
+
diff --git a/doc/pjsip-book/media_quality.rst b/doc/pjsip-book/media_quality.rst
index ad81557c..e4224ec9 100644
--- a/doc/pjsip-book/media_quality.rst
+++ b/doc/pjsip-book/media_quality.rst
@@ -1,11 +1,30 @@
 
-

-Media Quality

-*************

-

-Audio Quality

-=============

-

-Video Quality

-=============

-

+Media Quality
+*************
+
+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
+
diff --git a/doc/pjsip-book/network_problems.rst b/doc/pjsip-book/network_problems.rst
index c16ef0b3..4fadc4ed 100644
--- a/doc/pjsip-book/network_problems.rst
+++ b/doc/pjsip-book/network_problems.rst
@@ -1,11 +1,16 @@
 
-

-Network Problems

-****************

-

-IP Address Change

-=================

-

-Blocked/Filtered Network

-========================

-

+Network Problems
+****************
+
+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
+
diff --git a/doc/pjsip-book/optimization.rst b/doc/pjsip-book/optimization.rst
index ad0932ed..c04bf1c0 100644
--- a/doc/pjsip-book/optimization.rst
+++ b/doc/pjsip-book/optimization.rst
@@ -1,11 +1,13 @@
 
-

-General Configuration Optimization

-**********************************

-

-PJSUA2 Settings

-===============

-

-CPU Optimization

-================

-

+General Configuration Optimization
+**********************************
+
+PJSUA2 Settings
+===============
+
+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
+
diff --git a/doc/pjsip-book/presence.rst b/doc/pjsip-book/presence.rst
index ab544cce..880dba72 100644
--- a/doc/pjsip-book/presence.rst
+++ b/doc/pjsip-book/presence.rst
@@ -1,43 +1,108 @@
 
-

-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.

-

-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::

-

-  class MyBuddyCallback(pjsua.BuddyCallback):

-    def __init__(self, buddy=None):

-        pjsua.BuddyCallback.__init__(self, buddy)

-

-    def on_state(self):

-        print "Buddy", self.buddy.info().uri, "is",

-        print self.buddy.info().online_text

-

-  try:

-    uri = '"Alice" <sip:alice@example.com>'

-    buddy = acc.add_buddy(uri, cb=MyBuddyCallback())

-    buddy.subscribe()

-

-  except pjsua.Error, err:

-    print 'Error adding buddy:', err

-

-For more information please see ​Buddy class and ​BuddyCallback 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.

-

-Changing Account's Presence Status

-

-The ​Account class provides two methods to change account's presence status:

-

-​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.

-

+Buddy (Presence)
+================
+Presence feature in PJSUA2 centers around Buddy class. This class represents a remote buddy (a person, or a SIP endpoint).
+
+Subclassing the Buddy class
+----------------------------
+To use the Buddy class, normally application SHOULD create its own subclass, such as:
+
+.. code-block:: c++
+
+    class MyBuddy : public Buddy
+    {
+    public:
+        MyBuddy() {}
+        ~MyBuddy() {}
+
+        virtual void onBuddyState();
+    };
+
+In its subclass, application can implement the buddy callback to get the notifications on buddy state change.
+
+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 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:
+
+.. code-block:: c++
+
+    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
+
+
diff --git a/doc/pjsip-book/reference.rst b/doc/pjsip-book/reference.rst
index c595269d..721e3fcb 100644
--- a/doc/pjsip-book/reference.rst
+++ b/doc/pjsip-book/reference.rst
@@ -1,20 +1,19 @@
 
-

-PJSUA2 API Reference Manuals

-****************************

-

-Endpoint

-========

-

-Account

-=======

-

-Media

-=====

-

-Call

-====

-

-Buddy

-=====

-

+PJSUA2 API Reference Manuals
+****************************
+
+Endpoint
+========
+
+Account
+=======
+
+Media
+=====
+
+Call
+====
+
+Buddy
+=====
+
diff --git a/doc/pjsip-book/samples.rst b/doc/pjsip-book/samples.rst
index 3c951ede..7c8191d8 100644
--- a/doc/pjsip-book/samples.rst
+++ b/doc/pjsip-book/samples.rst
@@ -1,27 +1,33 @@
 
-

-PJSUA2 Sample Applications

-***********************************

-

-Sample Apps

-===========

-

-Python GUI

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

-It requires Python 2.7 and above.

-

-Android & Java

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

-

-C++

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

-

-Miscellaneous

-===================

-

-How to dump call stats

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

-

-How to …

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

-

+PJSUA2 Sample Applications
+***********************************
+
+Sample Apps
+===========
+
+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
+------------------
+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::
+
+    python application.py
+
+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 
+-----------------------------
+