sjero.net Git - linphone/blob - java/common/org/linphone/core/package.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5
   6   @(#)package.html
   7
   8 Copyright (C) 2010  Belledonne Communications, Grenoble, France
   9
  10 This program is free software; you can redistribute it and/or
  11 modify it under the terms of the GNU General Public License
  12 as published by the Free Software Foundation; either version 2
  13 of the License, or (at your option) any later version.
  14
  15 This program is distributed in the hope that it will be useful,
  16 but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 GNU General Public License for more details.
  19
  20 You should have received a copy of the GNU General Public License
  21 along with this program; if not, write to the Free Software
  22 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23
  24
  25 -->
  26 </head>
  27 <body bgcolor="white">
  28
  29 Liblinphone is a high level library for bringing SIP video call functionnality into an application. It aims at making easy the integration of the SIP video calls into any applications. All variants of linphone are directly based on it:
  30
  31         <li>linphone (GUI interface)
  32         <li>linphonec (console interface)
  33 <br> Liblinphone is GPL (see COPYING file). Please understand the licencing details before using it!
  34
  35 <br>For any use of this library beyond the rights granted to you by the GPL license, please contact Belledonne Communications (contact@belledonne-communications.com)
  36
  37
  38
  39
  40 <h2>Package Specification</h2>
  41
  42 LibLinphone package is organized in submodules.
  43 <ul>
  44   <li><a href="#proxy">Managing proxies</a></li>
  45 </ul>
  46 <ul>
  47   <li><a href="#buddy">Managing Buddies and buddy list and presence</a></li>
  48 </ul>
  49 <ul>
  50   <li><a href="#chat">Chat room and Messaging</a></li>
  51 </ul>
  52 <ul>
  53   <li><a href="#echo">Sound and echo cancellation settings</a></li>
  54 </ul>
  55
  56
  57 <h2>Related Documentation</h2>
  58
  59 For overviews, tutorials, examples, guides, and tool documentation, please see:
  60 <ul>
  61   <li><a href="http://www.linphone.org">linphone web site</a>
  62 </ul>
  63
  64 <!-- Put @see and @since tags down here. -->
  65 <h3>
  66 <a name="proxy">Managing proxies</a>
  67 </h3>
  68 User registration is controled by  {@link org.linphone.core.LinphoneProxyConfig } settings.
  69 <br> Each {@link org.linphone.core.LinphoneProxyConfig } object can be configured with registration informations
  70 like {@link org.linphone.core.LinphoneProxyConfig#setProxy proxy address } , {@link org.linphone.core.LinphoneProxyConfig#setIdentity user id}, and so on.
  71 <br> A created proxy config using {@link org.linphone.core.LinphoneCoreFactory#createProxyConfig }, once configured, must be added to {@link org.linphone.core.LinphoneCore} using function {@link org.linphone.core.LinphoneCore#addProxyConfig }.
  72 <br> It is recommended to set a default {@link org.linphone.core.LinphoneProxyConfig proxy config }  using function {@link org.linphone.core.LinphoneCore#setDefaultProxyConfig }. Once done, if {@link org.linphone.core.LinphoneProxyConfig a proxy config } has been configured with attribute {@link org.linphone.core.LinphoneProxyConfig#enableRegister enable register }  , next call to {@link org.linphone.core.LinphoneCore#iterate } triggers a SIP register.
  73 <br> Registration status is reported by {@link org.linphone.core.LinphoneCoreListener#registrationState registration listener}.
  74 <br>
  75 <br> This pseudo code demonstrates basic registration operations:
  76 <br>
  77 <pre>
  78 <code>
  79
  80         LinphoneProxyConfig proxy_cfg;
  81         /*create proxy config*/
  82         proxy_cfg = LinphoneCoreFactory.instance().createProxyConfig();
  83         /*parse identity*/
  84         LinphoneAddress from = LinphoneCoreFactory.instance().createAddress("sip:toto@sip.titi.com");
  85         LinphoneAuthInfo info;
  86         if (password!=NULL){
  87                 info=LinphoneCoreFactory.instance().createAuthInfo(from.getUsername(),null,"secret",null,null); /*create authentication structure from identity*/
  88                 lc.addAuthInfo(info); /*add authentication info to LinphoneCore*/
  89         }
  90         // configure proxy entries
  91         proxy_cfg.setIdenty(identity); /*set identity with user name and domain*/
  92         String server_addr = from.getDomain(); /*extract domain address from identity*/
  93         proxy_cfg.setProxy(server_addr); /* we assume domain = proxy server address*/
  94         proxy_cfg.enableRegister(true); /*activate registration for this proxy config*/
  95
  96         lc.addProxyConfig(proxy_cfg); /*add proxy config to linphone core*/
  97         lc.setDefaultProxyconfig(proxy_cfg); /*set to default proxy*/
  98 </code>
  99 </pre>
 100 <br>
 101   {@link org.linphone.core.LinphoneCoreListener#registrationState Registration state listener} :
 102 <pre>
 103 <code>
 104  void registrationState(LinphoneCore lc, LinphoneProxyConfig cfg, LinphoneCore.RegistrationState cstate, String message){
 105                 System.out.println(New registration state ["+cstate+"] for user id ["+cfg.getUserName()+"] at proxy ["+cfg.getProxy()+"]";
 106 }
 107 </pre>
 108 </code>
 109
 110 <br><b>Authentication:</b>
 111 <br>Most of the time, registration requires {@link org.linphone.core.LinphoneAuthInfo authentication } to succed. {@link org.linphone.core.LinphoneAuthInfo} info must be either added to {@link org.linphone.core.LinphoneCore } using method {@link org.linphone.core.LinphoneCore#addAuthInfo } before {@link org.linphone.core.LinphoneProxyConfig} is added to Linphone core, or on demand from listener {@link org.linphone.core.LinphoneCoreListener#authInfoRequested(LinphoneCore, String, String)}  .
 112 <br>
 113 <br><b>Unregistration:</b>
 114 <br> Unregistration or any changes to {@link org.linphone.core.LinphoneProxyConfig} must be first started by a call to function {@link org.linphone.core.LinphoneProxyConfig#edit } and validated by  function {@link org.linphone.core.LinphoneProxyConfig#done }
 115 <br> This pseudo code shows how to unregister a user associated to a{@link org.linphone.core.LinphoneProxyConfig}
 116 <pre>
 117 <code>
 118         LinphoneProxyConfig proxy_cfg;
 119         lc.setDefaultProxyConfig(proxy_cfg); /* get default proxy config*/
 120         proxy_cfg.edit(); /*start editing proxy configuration*/
 121         proxy_cfg.enableRegister(false); /*de-activate registration for this proxy config*/
 122         proxy_cfg.done(); /*initiate REGISTER with expire = 0*/
 123 </pre>
 124 </code>
 125 <br>
 126 <br>
 127 <h3>
 128 <a name="buddy">Managing Buddies and buddy list and presence</a>
 129 </h3>
 130 <br>
 131 <b>Buddies and buddy list</b>
 132 <br>Each buddy is represented by a {@link org.linphone.core.LinphoneFriend } object created by function {@link org.linphone.core.LinphoneCoreFactory#createLinphoneFriend()}.
 133 Buddy configuration parameters like {@link org.linphone.core.LinphoneFriend#setAddress(LinphoneAddress) sip uri} or  {@link org.linphone.core.LinphoneFriend#setIncSubscribePolicy(LinphoneFriend.SubscribePolicy) status publication}  are configurable for each buddy.
 134 <br>Here under a typical buddy creation:
 135 <br>
 136 <pre>
 137 <code>
 138         LinphoneFriend my_friend=LinphoneFactory.instance().createFriend("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
 139         my_friend.enableSubscribes(true); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
 140         my_friend.setIncSubscribePolicy(LinphoneFriend.SubscribePolicy.Accept); /* accept Incoming subscription request for this friend*/
 141 </code>
 142 </pre>
 143 {@link LinphoneFriend  friends } status changes are reported by  {@link org.linphone.core.LinphoneCoreListener#notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf)} .
 144 <pre>
 145 <code>
 146  void notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf){
 147         LinphoneAddress friend_address = lf.getAddress();
 148         System.out.println("New state ["+lf.getStatus()+"] for user id ["+friend_address+"] ");
 149 }
 150 </code>
 151 </pre>
 152
 153 <br>Once created a buddy can be added to the buddy list using function {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf) } . Added friends will be notified about {@link org.linphone.core.LinphoneCore#setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status) local status changes }
 154 <br>
 155 Any subsequente modifications to {@link org.linphone.core.LinphoneFriend} must be first started by a call to function  to {@link org.linphone.core.LinphoneFriend#edit()} and validated by  function {@link org.linphone.core.LinphoneFriend#done()}
 156 <pre>
 157 <code>
 158         my_friend.edit(); /* start editing friend */
 159         my_friend.enableSubscribes(true); /*disable subscription for this friend*/
 160         my_friend.done(); /*commit changes triggering an UNSUBSCRIBE message*/
 161 </code>
 162 </pre>                  Do not display status messages
 163 -J<flag>                  Pass <flag> directly to the runtime system
 164
 165 Provided by Standard doclet:
 166 -d <directory>                    Destination directory for output files
 167 -use
 168
 169 <b> Publishing presence status </b>
 170 <br>Local presence status can be changed using function {@link org.linphone.core.LinphoneCore#setPresenceInfo }.New status is propagated to all friends {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf)  previously added } to LinphoneCore.
 171 <br>
 172 <br>
 173 <b>Handling incoming subscription request</b>
 174 <br> New incoming subscription requests are process according to{@link org.linphone.core.LinphoneFriend#setIncSubscribePolicy(LinphoneFriend.SubscribePolicy)  the incoming subscription policy state}  for subscription initiated by {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf) members of the buddy list. }
 175 <br> For incoming request coming from an unknown buddy, the call back  {@link org.linphone.core.LinphoneCoreListener#newSubscriptionRequest(LinphoneCore lc, LinphoneFriend lf, String url)}
 176
 177 <h3>
 178 <a name="chat">Chat room and Messaging</a>
 179 </h3>
 180 <b> Exchanging text messages</b>
 181 <br> Messages are sent using {@link org.linphone.core.LinphoneChatRoom} object. First step is to create a {@link org.linphone.core.LinphoneCore#createChatRoom chat room }
 182 from a peer sip uri.
 183 <pre>
 184 <code>
 185         LinphoneChatRoom chat_room = lc.createChatRoom("sip:joe@sip.linphone.org");
 186 </pre>
 187 </code>
 188 <br>Once created, messages are sent using function {@link org.linphone.core.LinphoneChatRoom#sendMessage }  .
 189 <pre>
 190 <code>
 191         chat_room.sendMessage("Hello world"); /*sending message*/
 192 </pre>
 193 </code>
 194 <br>Incoming message are received from {@link org.linphone.core.LinphoneCoreListener#textReceived  a listener }
 195 <pre>
 196 <code>
 197         void textReceived(LinphoneCore lc, LinphoneChatRoom cr,LinphoneAddress from,String message) {
 198                 System.out.println("Message ["+message+"] received from ["+from+"] ");
 199         }
 200 </code>
 201 </pre>
 202
 203 <h3>
 204 <a name="echo">Sound and echo cancellation settings</a>
 205 </h3>
 206 <b>Sound levels</b>
 207 <br>
 208 It is possible to tune the microphone input gain and speaker/receiver output gain by setting parameters into the linphonerc factory config file loaded when instanciating the {@link org.linphone.core.LinphoneCore LinphoneCore}. These gains are liblinphone's internal software gains and are unrelated to volume levels managed by the operating system. For example: <br>
 209 <pre>
 210 <code>
 211 [sound]
 212 #set the speaker or receiver playback gain in dbm0 (0 db = no change).
 213 playback_gain_db=-3
 214 #set the microphone gain in linear scale:
 215 mic_gain=0.1
 216 </code>
 217 </pre>
 218
 219 <br>
 220
 221 <b>Echo cancellation</b>
 222 <br>
 223 On Android devices, echo is a problem, especially with low-end devices. The root cause is the unpredictable latency of Android's sound system. The liblinphone software {@link org.linphone.core.LinphoneCore#enableEchoCancellation echo canceller} that is operating well on desktop platforms (Mac, Linux, Windows) is unable to operate under Android platform. The situation is very heterogenous:<br>
 224 <ul>
 225         <li>On new (after 2011) high end devices, manufacturers often include a hardware echo cancellation. If available, liblinphone will make use of it and no software correction is required.
 226         Source file linphone-android/submodules/linphone/mediastreamer2/java/src/org/linphone/mediastream/video/capture/hwconf/Hacks.java contains a method hasBuiltInEchoCanceller() that returns true if an hardware echo canceller is available, based on device model identifier. The current list is incomplete.
 227         </li>
 228         <li>On former models with decent CPU power (armv7), sound system behaves in a nearly predictive way so that it is possible to use {@link org.linphone.core.LinphoneCore#enableEchoLimiter echo limiter}. Echo limiter is a simple echo attenuation technique which consists in strongly attenuating the microphone input when speaker is playing voice, in order to cut the echo. The main drawback of echo limiter is that the conversation is perceived as half duplex by users, because they won't hear background noise from the remote side while they are speaking.
 229         </li>
 230         <li>On low class android devices or very old models (armv5 processor), no solution works.
 231         </li>
 232 </ul>
 233
 234 <br>
 235 In order to benefit from the best echo cancellation solution, we recommend applications to run the following algorithm, when it is run for the first time:<br>
 236 First of {@link org.linphone.core.LinphoneCore#enableEchoCancellation echo canceller} should not be used, in any case.
 237 <ul>
 238         <li>Use the Hacks.hasBuiltInEchoCanceller() method to first check if the device has hardware echo canceller. If yes, then echo limiter must be turned off.</li>
 239         <li>If no the hasBuiltInEchoCanceller() returned false, then it is possible to use the echo calibration procedure. If the calibration procedure fails, it means that
 240         probably the phone performs hardware echo cancellation, so in this case echo limiter must be turned off.</li>
 241         <li>If the echo calibration succeeded, then echo is present, so it is recommended to enable echo limiter.
 242 </ul>
 243
 244 <br>
 245 <b>Echo calibration procedure</b>
 246 <br>
 247 The echo calibration procedure is a five second test which consists in playing small beeps to the speaker while the microphone input is recorded.
 248 If the device is subject to echo (or doesn't have hardware echo cancellation), then beeps recorded by the microphone will be detected and a measurement of echo delay can be computed.
 249 Echo calibration procedure can be started by calling {@link org.linphone.core.LinphoneCore#startEchoCalibration LinphoneCore.startEchoCalibration}.
 250
 251 <br><br>
 252 <b>Echo limiter settings</b><br>
 253 Echo limiter requires settings to be defined in linphonerc factory config file for correction operation.
 254 Typical settings are:
 255 <pre>
 256 <code>
 257 [sound]
 258 el_type=mic
 259 #speaker energy threshold (linear scale) above which echo limiter decreases mic gain.
 260 el_thres=0.03
 261 #attenuation applied to mic gain (linear scale)
 262 el_force=100000
 263 #minimum time in milliseconds during which attenuation is applied
 264 el_sustain=600
 265 #double talk detection: threshold of ratio mic-energy/speaker-energy above which mic input is sent anyway.
 266 el_transmit_thres=1.7
 267 #noise gate floorgain (gain applied when no voice is detected).
 268 ng_floorgain=0.01
 269 </code>
 270 </pre>
 271
 272 Up to date settings must be found from linphone-android/res/raw/linphonerc file.
 273
 274 <br>
 275
 276 </body>
 277 </html>