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


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

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/account

    v1 v1  
     1{{{ 
     2#!rst 
     3 
     4Accounts 
     5========= 
     6​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. 
     7 
     8Account 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. 
     9 
     10At 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. 
     11 
     12Also 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. 
     13 
     14Subclassing the Account class 
     15--------------------------------- 
     16To use the Account class, application MUST create its own subclass, such as:: 
     17 
     18    class MyAccount : public Account 
     19    { 
     20    public: 
     21        MyAccount() {} 
     22        ~MyAccount() {} 
     23 
     24        virtual void onRegState(OnRegStateParam &prm) 
     25        { 
     26            AccountInfo ai = getInfo(); 
     27            cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=") 
     28                 << prm.code << endl; 
     29 
     30      } 
     31     
     32        virtual void onIncomingCall(OnIncomingCallParam &iprm) 
     33        { 
     34            Call *call = new MyCall(*this, iprm.callId); 
     35            // Delete the call, which will also hangup the call 
     36            delete call; 
     37        } 
     38    }; 
     39 
     40In its subclass, application can implement the account callbacks, which is basically used to process events related to the account, such as: 
     41 
     42- the status of SIP registration 
     43- incoming calls 
     44- incoming presence subscription requests 
     45- incoming instant message not from buddy 
     46 
     47Application needs to override the relevant callback methods in the derived class to handle these particular events. 
     48 
     49If the events are not handled, default actions will be invoked: 
     50 
     51- incoming calls will not be handled 
     52- incoming presence subscription requests will be accepted 
     53- incoming instant messages from non-buddy will be ignored 
     54 
     55Creating Userless Accounts 
     56-------------------------- 
     57A 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. 
     58 
     59So for example, we might identify ourselves as "sip:192.168.0.15" (a userless account) rather than, say, "sip:bennylp@pjsip.org". 
     60 
     61In 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. 
     62 
     63Here's a snippet:: 
     64 
     65    AccountConfig acc_cfg; 
     66    acc_cfg.sipConfig.transportId = tid; 
     67    MyAccount *acc = new MyAccount; 
     68    try { 
     69        acc->create(acc_cfg); 
     70    } catch(Error& err) { 
     71        cout << "Account creation error: " << err.reason << endl; 
     72    } 
     73 
     74Once the account is created, you can use the instance as a normal account. More will be explained later. 
     75 
     76Accounts 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. 
     77 
     78Creating Account 
     79--------------- 
     80For the "normal" account, we need to configure ​AccountConfig and call ​Account.create() to create the account. 
     81 
     82At 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:: 
     83 
     84    AccountConfig acc_cfg; 
     85    acc_cfg.idUri = "sip:test1@pjsip.org"; 
     86    MyAccount *acc = new MyAccount; 
     87    try { 
     88        acc->create(acc_cfg); 
     89    } catch(Error& err) { 
     90        cout << "Account creation error: " << err.reason << endl; 
     91    } 
     92 
     93The 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. 
     94 
     95Typically 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:: 
     96 
     97    AccountConfig acc_cfg; 
     98    acc_cfg.idUri = "sip:test1@pjsip.org"; 
     99    acc_cfg.regConfig.registrarUri = "sip:pjsip.org"; 
     100    acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "test1") ); 
     101    MyAccount *acc = new MyAccount; 
     102    try { 
     103        acc->create(acc_cfg); 
     104    } catch(Error& err) { 
     105        cout << "Account creation error: " << err.reason << endl; 
     106    } 
     107 
     108Account Configurations 
     109----------------------- 
     110There are many more settings that can be specified in ​AccountConfig, like: 
     111 
     112​- AccountRegConfig, to specify registration settings, such as registrar server and retry interval. 
     113- AccountSipConfig, to specify SIP settings, such as credential information and proxy server. 
     114- AccountCallConfig, to specify call settings, such as whether reliable provisional response (SIP 100rel) is required. 
     115- AccountPresConfig, to specify presence settings, such as whether presence publication (PUBLISH) is enabled. 
     116- AccountMwiConfig, to specify MWI (Message Waiting Indication) settings. 
     117- AccountNatConfig, to specify NAT settings, such as whether STUN or ICE is used. 
     118- AccountMediaConfig, to specify media settings, such as Secure RTP (SRTP) related settings. 
     119- AccountVideoConfig, to specify video settings, such as default capture and render device. 
     120 
     121Please see ​AccountConfig reference documentation for more info. 
     122 
     123Account Operations 
     124-------------------------------------- 
     125Some of the operations to the ​Account object: 
     126 
     127- add buddy objects 
     128- set account's presence online status 
     129- stop/start SIP registration 
     130 
     131Please see the reference documentation for Account for more info. Calls, presence, and buddy list will be explained in later sections. 
     132 
     133 
     134}}}