Changeset 4762 for pjproject/trunk/doc/pjsip-book/account.rst
- Timestamp:
- Feb 24, 2014 11:00:15 AM (10 years ago)
- Location:
- pjproject/trunk/doc/pjsip-book
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/doc/pjsip-book
-
Property
svn:ignore
set to
xml
-
Property
svn:ignore
set to
-
pjproject/trunk/doc/pjsip-book/account.rst
r4704 r4762 1 2 1 3 2 Accounts 4 3 ========= 5 â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 identityis used as the From header in outgoing requests.6 7 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 onlinestatus, 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.4 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. 5 6 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. 8 7 9 8 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. 10 9 11 Also one account must be set as the default account, which will be used as the account identity when pjsua fails to match therequest with any accounts using the stricter matching rules.10 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. 12 11 13 12 Subclassing the Account class 14 13 --------------------------------- 15 To use the Account class, normally application SHOULD create its own subclass, such as:: 14 To use the Account class, normally application SHOULD create its own subclass, in order to receive notifications for the account. For example: 15 16 .. code-block:: c++ 16 17 17 18 class MyAccount : public Account … … 26 27 cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=") 27 28 << prm.code << endl; 28 29 29 } 30 30 … … 32 32 { 33 33 Call *call = new MyCall(*this, iprm.callId); 34 // Delete the call, which will also hangup the call 34 35 // Just hangup for now 36 CallOpParam op; 37 op.statusCode = PJSIP_SC_DECLINE; 38 call->hangup(op); 39 40 // And delete the call 35 41 delete call; 36 42 } … … 54 60 Creating Userless Accounts 55 61 -------------------------- 56 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. 57 58 So for example, we might identify ourselves as "sip:192.168.0.15" (a userless account) rather than, say, "sip:bennylp@pjsip.org". 59 60 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. 61 62 Here's a snippet:: 62 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". 63 64 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. 65 66 67 Creating Account 68 ---------------- 69 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: 70 71 .. code-block:: c++ 63 72 64 73 AccountConfig acc_cfg; 65 acc_cfg.sipConfig.transportId = tid; 74 acc_cfg.idUri = "sip:test1@pjsip.org"; 75 66 76 MyAccount *acc = new MyAccount; 67 77 try { 68 78 acc->create(acc_cfg); 69 79 } catch(Error& err) { 70 cout << "Account creation error: " << err. reason<< endl;80 cout << "Account creation error: " << err.info() << endl; 71 81 } 72 82 73 Once the account is created, you can use the instance as a normal account. More will be explained later. 74 75 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. 76 77 Creating Account 78 ---------------- 79 For the "normal" account, we need to configure âAccountConfig and call âAccount.create() to create the account. 80 81 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:: 83 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. 84 85 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: 86 87 .. code-block:: c++ 82 88 83 89 AccountConfig acc_cfg; 84 90 acc_cfg.idUri = "sip:test1@pjsip.org"; 91 acc_cfg.regConfig.registrarUri = "sip:pjsip.org"; 92 acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "secret1") ); 93 85 94 MyAccount *acc = new MyAccount; 86 95 try { 87 96 acc->create(acc_cfg); 88 97 } catch(Error& err) { 89 cout << "Account creation error: " << err.reason << endl; 90 } 91 92 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. 93 94 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:: 95 96 AccountConfig acc_cfg; 97 acc_cfg.idUri = "sip:test1@pjsip.org"; 98 acc_cfg.regConfig.registrarUri = "sip:pjsip.org"; 99 acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "test1") ); 100 MyAccount *acc = new MyAccount; 101 try { 102 acc->create(acc_cfg); 103 } catch(Error& err) { 104 cout << "Account creation error: " << err.reason << endl; 98 cout << "Account creation error: " << err.info() << endl; 105 99 } 106 100 107 101 Account Configurations 108 102 ----------------------- 109 There are many more settings that can be specified in âAccountConfig, like:103 There are many more settings that can be specified in AccountConfig, like: 110 104 111 105 - AccountRegConfig, to specify registration settings, such as registrar server and retry interval. … … 118 112 - AccountVideoConfig, to specify video settings, such as default capture and render device. 119 113 120 Please see âAccountConfig reference documentation for more info.114 Please see AccountConfig reference documentation for more info. 121 115 122 116 Account Operations 123 117 -------------------------------------- 124 Some of the operations to the âAccount object: 125 126 - add buddy objects 127 - set account's presence online status 128 - stop/start SIP registration 129 130 Please see the reference documentation for Account for more info. Calls, presence, and buddy list will be explained in later sections. 131 132 118 Some of the operations to the Account object: 119 120 - manage registration 121 - manage buddies/contacts 122 - manage presence online status 123 124 Please see the reference documentation for Account for more info. Calls, presence, and buddy will be explained in later chapters. 125 126 127 Class Reference 128 --------------- 129 Account 130 +++++++ 131 .. doxygenclass:: pj::Account 132 :path: xml 133 :members: 134 135 AccountInfo 136 +++++++++++ 137 .. doxygenstruct:: pj::AccountInfo 138 :path: xml 139 140 Account Settings 141 ++++++++++++++++ 142 AccountConfig 143 ~~~~~~~~~~~~~ 144 .. doxygenstruct:: pj::AccountConfig 145 :path: xml 146 147 AccoutRegConfig 148 ~~~~~~~~~~~~~~~ 149 .. doxygenstruct:: pj::AccountRegConfig 150 :path: xml 151 152 AccountSipConfig 153 ~~~~~~~~~~~~~~~~ 154 .. doxygenstruct:: pj::AccountSipConfig 155 :path: xml 156 157 AccountCallConfig 158 ~~~~~~~~~~~~~~~~~ 159 .. doxygenstruct:: pj::AccountCallConfig 160 :path: xml 161 162 AccountPresConfig 163 ~~~~~~~~~~~~~~~~~ 164 .. doxygenstruct:: pj::AccountPresConfig 165 :path: xml 166 167 AccountMwiConfig 168 ~~~~~~~~~~~~~~~~ 169 .. doxygenstruct:: pj::AccountMwiConfig 170 :path: xml 171 172 AccountNatConfig 173 ~~~~~~~~~~~~~~~~ 174 .. doxygenstruct:: pj::AccountNatConfig 175 :path: xml 176 177 AccountMediaConfig 178 ~~~~~~~~~~~~~~~~~~ 179 .. doxygenstruct:: pj::AccountMediaConfig 180 :path: xml 181 182 AccountVideoConfig 183 ~~~~~~~~~~~~~~~~~~ 184 .. doxygenstruct:: pj::AccountVideoConfig 185 :path: xml 186 187 188 Callback Parameters 189 +++++++++++++++++++ 190 .. doxygenstruct:: pj::OnIncomingCallParam 191 :path: xml 192 193 .. doxygenstruct:: pj::OnRegStartedParam 194 :path: xml 195 196 .. doxygenstruct:: pj::OnRegStateParam 197 :path: xml 198 199 .. doxygenstruct:: pj::OnIncomingSubscribeParam 200 :path: xml 201 202 .. doxygenstruct:: pj::OnInstantMessageParam 203 :path: xml 204 205 .. doxygenstruct:: pj::OnInstantMessageStatusParam 206 :path: xml 207 208 .. doxygenstruct:: pj::OnTypingIndicationParam 209 :path: xml 210 211 .. doxygenstruct:: pj::OnMwiInfoParam 212 :path: xml 213 214 .. doxygenstruct:: pj::PresNotifyParam 215 :path: xml 216 217 Other 218 +++++ 219 .. doxygenclass:: pj::FindBuddyMatch 220 :path: xml 221 :members: 222
Note: See TracChangeset
for help on using the changeset viewer.