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

   1 /*
   2 LinphoneCore.java
   3 Copyright (C) 2010  Belledonne Communications, Grenoble, France
   4
   5 This program is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU General Public License
   7 as published by the Free Software Foundation; either version 2
   8 of the License, or (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18 */
  19 package org.linphone.core;
  20
  21 import java.util.Vector;
  22
  23 import org.linphone.core.LinphoneCall.State;
  24 import org.linphone.mediastream.video.capture.hwconf.AndroidCameraConfiguration;
  25
  26 /**
  27  * Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.
  28  *
  29  */
  30
  31 public interface LinphoneCore {
  32         /**
  33          * linphone core states
  34          */
  35         static public class GlobalState {
  36
  37                 static private Vector<GlobalState> values = new Vector<GlobalState>();
  38                 /**
  39                  * Off
  40                  */
  41                 static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");
  42                 /**
  43                  * Startup
  44                  */
  45                 static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
  46                 /**
  47                  * On
  48                  */
  49                 static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
  50                 /**
  51                  * Shutdown
  52                  */
  53                 static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
  54
  55                 private final int mValue;
  56                 private final String mStringValue;
  57
  58
  59                 private GlobalState(int value,String stringValue) {
  60                         mValue = value;
  61                         values.addElement(this);
  62                         mStringValue=stringValue;
  63                 }
  64                 public static GlobalState fromInt(int value) {
  65
  66                         for (int i=0; i<values.size();i++) {
  67                                 GlobalState state = (GlobalState) values.elementAt(i);
  68                                 if (state.mValue == value) return state;
  69                         }
  70                         throw new RuntimeException("state not found ["+value+"]");
  71                 }
  72                 public String toString() {
  73                         return mStringValue;
  74                 }
  75         }
  76         /**
  77          * Describes proxy registration states.
  78          *
  79          */
  80         static public class RegistrationState {
  81
  82                 private static Vector<RegistrationState> values = new Vector<RegistrationState>();
  83                 /**
  84                  * None
  85                  */
  86                 public static RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");
  87                 /**
  88                  * In Progress
  89                  */
  90                 public static RegistrationState RegistrationProgress  = new RegistrationState(1,"RegistrationProgress");
  91                 /**
  92                  * Ok
  93                  */
  94                 public static RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
  95                 /**
  96                  * Cleared
  97                  */
  98                 public static RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
  99                 /**
 100                  * Failed
 101                  */
 102                 public static RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
 103                 private final int mValue;
 104                 private final String mStringValue;
 105
 106
 107                 private RegistrationState(int value,String stringValue) {
 108                         mValue = value;
 109                         values.addElement(this);
 110                         mStringValue=stringValue;
 111                 }
 112                 public static RegistrationState fromInt(int value) {
 113
 114                         for (int i=0; i<values.size();i++) {
 115                                 RegistrationState state = (RegistrationState) values.elementAt(i);
 116                                 if (state.mValue == value) return state;
 117                         }
 118                         throw new RuntimeException("state not found ["+value+"]");
 119                 }
 120                 public String toString() {
 121                         return mStringValue;
 122                 }
 123         }
 124         /**
 125          * Describes firewall policy.
 126          *
 127          */
 128         static public class FirewallPolicy {
 129
 130                 static private Vector<FirewallPolicy> values = new Vector<FirewallPolicy>();
 131                 /**
 132                  * No firewall is assumed.
 133                  */
 134                 static public FirewallPolicy NoFirewall = new FirewallPolicy(0,"NoFirewall");
 135                 /**
 136                  * Use NAT address (discouraged)
 137                  */
 138                 static public FirewallPolicy UseNatAddress  = new FirewallPolicy(1,"UseNatAddress");
 139                 /**
 140                  * Use stun server to discover RTP addresses and ports.
 141                  */
 142                 static public FirewallPolicy UseStun = new FirewallPolicy(2,"UseStun");
 143                 /**
 144                  * Use ICE.
 145                  */
 146                 static public FirewallPolicy UseIce = new FirewallPolicy(3,"UseIce");
 147                 /**
 148                  * Use uPnP.
 149                  */
 150                 static public FirewallPolicy UseUpnp = new FirewallPolicy(4,"UseUpnp");
 151
 152                 private final int mValue;
 153                 private final String mStringValue;
 154
 155
 156                 private FirewallPolicy(int value,String stringValue) {
 157                         mValue = value;
 158                         values.addElement(this);
 159                         mStringValue=stringValue;
 160                 }
 161                 public static FirewallPolicy fromInt(int value) {
 162
 163                         for (int i=0; i<values.size();i++) {
 164                                 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
 165                                 if (state.mValue == value) return state;
 166                         }
 167                         throw new RuntimeException("state not found ["+value+"]");
 168                 }
 169                 public String toString() {
 170                         return mStringValue;
 171                 }
 172                 public int value(){
 173                         return mValue;
 174                 }
 175         }
 176
 177         /**
 178          * Linphone core SIP transport ports.
 179          * Use with {@link LinphoneCore#setSignalingTransportPorts(Transports)}
 180          * @ingroup initializing
 181          */
 182         static public class Transports {
 183                 /**
 184                  * udp port to listening on, negative value if not set
 185                  * */
 186                 public int udp;
 187                 /**
 188                  * tcp port to listening on, negative value if not set
 189                  * */
 190                 public int tcp;
 191                 /**
 192                  * tls port to listening on, negative value if not set
 193                  * */
 194                 public int tls;
 195
 196                 public Transports() {};
 197                 public Transports(Transports t) {
 198                         this.udp = t.udp;
 199                         this.tcp = t.tcp;
 200                         this.tls = t.tls;
 201                 }
 202                 public String toString() {
 203                         return "udp["+udp+"] tcp["+tcp+"] tls["+tls+"]";
 204                 }
 205         }
 206         /**
 207          * Media (RTP) encryption enum-like.
 208          *
 209          */
 210         static public final class MediaEncryption {
 211
 212                 static private Vector<MediaEncryption> values = new Vector<MediaEncryption>();
 213                 /**
 214                  * None
 215                  */
 216                 static public final MediaEncryption None = new MediaEncryption(0,"None");
 217                 /**
 218                  * SRTP
 219                  */
 220                 static public final MediaEncryption SRTP = new MediaEncryption(1,"SRTP");
 221                 /**
 222                  * ZRTP
 223                  */
 224                 static public final MediaEncryption ZRTP = new MediaEncryption(2,"ZRTP");
 225                 protected final int mValue;
 226                 private final String mStringValue;
 227
 228
 229                 private MediaEncryption(int value,String stringValue) {
 230                         mValue = value;
 231                         values.addElement(this);
 232                         mStringValue=stringValue;
 233                 }
 234                 public static MediaEncryption fromInt(int value) {
 235
 236                         for (int i=0; i<values.size();i++) {
 237                                 MediaEncryption menc = (MediaEncryption) values.elementAt(i);
 238                                 if (menc.mValue == value) return menc;
 239                         }
 240                         throw new RuntimeException("MediaEncryption not found ["+value+"]");
 241                 }
 242                 public String toString() {
 243                         return mStringValue;
 244                 }
 245         }
 246         /**
 247          *      EC Calibrator Status
 248          */
 249         static public class EcCalibratorStatus {
 250
 251                 static private Vector<EcCalibratorStatus> values = new Vector<EcCalibratorStatus>();
 252                 /* Do not change the values of these constants or the strings associated with them to prevent breaking
 253                    the collection of echo canceller calibration results during the wizard! */
 254                 public static final int IN_PROGRESS_STATUS=0;
 255                 public static final int DONE_STATUS=1;
 256                 public static final int FAILED_STATUS=2;
 257                 public static final int DONE_NO_ECHO_STATUS=3;
 258                 /**
 259                  * Calibration in progress
 260                  */
 261                 static public EcCalibratorStatus InProgress = new EcCalibratorStatus(IN_PROGRESS_STATUS,"InProgress");
 262                 /**
 263                  * Calibration done that produced an echo delay measure
 264                  */
 265                 static public EcCalibratorStatus Done = new EcCalibratorStatus(DONE_STATUS,"Done");
 266                 /**
 267                  * Calibration failed
 268                  */
 269                 static public EcCalibratorStatus Failed = new EcCalibratorStatus(FAILED_STATUS,"Failed");
 270                 /**
 271                  * Calibration done with no echo detected
 272                  */
 273                 static public EcCalibratorStatus DoneNoEcho = new EcCalibratorStatus(DONE_NO_ECHO_STATUS, "DoneNoEcho");
 274
 275                 private final int mValue;
 276                 private final String mStringValue;
 277
 278
 279                 private EcCalibratorStatus(int value,String stringValue) {
 280                         mValue = value;
 281                         values.addElement(this);
 282                         mStringValue=stringValue;
 283                 }
 284                 public static EcCalibratorStatus fromInt(int value) {
 285
 286                         for (int i=0; i<values.size();i++) {
 287                                 EcCalibratorStatus status = (EcCalibratorStatus) values.elementAt(i);
 288                                 if (status.mValue == value) return status;
 289                         }
 290                         throw new RuntimeException("status not found ["+value+"]");
 291                 }
 292                 public String toString() {
 293                         return mStringValue;
 294                 }
 295                 public int value(){
 296                         return mValue;
 297                 }
 298         }
 299
 300         static public class UpnpState {
 301                 static private Vector<UpnpState> values = new Vector<UpnpState>();
 302                 /**
 303                  * Idle
 304                  */
 305                 static public UpnpState Idle = new UpnpState(0, "Idle");
 306                 /**
 307                  * Pending
 308                  */
 309                 static public UpnpState Pending = new UpnpState(1, "Pending");
 310                 /**
 311                  * Adding
 312                  */
 313                 static public UpnpState Adding = new UpnpState(2, "Adding");
 314                 /**
 315                  * Removing
 316                  */
 317                 static public UpnpState Removing = new UpnpState(3, "Removing");
 318                 /**
 319                  * Not Available
 320                  */
 321                 static public UpnpState NotAvailable = new UpnpState(4, "Not available");
 322                 /**
 323                  * Ok
 324                  */
 325                 static public UpnpState Ok = new UpnpState(5, "Ok");
 326                 /**
 327                  * Ko
 328                  */
 329                 static public UpnpState Ko = new UpnpState(6, "Ko");
 330                 protected final int mValue;
 331                 private final String mStringValue;
 332
 333                 private UpnpState(int value, String stringValue) {
 334                         mValue = value;
 335                         values.addElement(this);
 336                         mStringValue = stringValue;
 337                 }
 338                 public static UpnpState fromInt(int value) {
 339                         for (int i = 0; i < values.size(); i++) {
 340                                 UpnpState mstate = (UpnpState) values.elementAt(i);
 341                                 if (mstate.mValue == value) return mstate;
 342                         }
 343                         throw new RuntimeException("UpnpState not found [" + value + "]");
 344                 }
 345                 public String toString() {
 346                         return mStringValue;
 347                 }
 348         }
 349
 350         /**
 351          * Set the context of creation of the LinphoneCore.
 352          */
 353         public void setContext(Object context);
 354
 355         /**
 356          * clear all added proxy configs
 357          */
 358         public void clearProxyConfigs();
 359         /**
 360          * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
 361          * @param proxyCfg
 362          * @throws LinphoneCoreException
 363          */
 364         public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
 365         /**
 366          * Sets the default proxy.
 367          *<br>
 368          * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
 369          * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
 370          * @param proxyCfg
 371          */
 372         public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
 373
 374         /**
 375          * get he default proxy configuration, that is the one used to determine the current identity.
 376          * @return null if no default proxy config
 377          */
 378         public LinphoneProxyConfig getDefaultProxyConfig() ;
 379
 380         /**
 381          * clear all the added auth info
 382          */
 383         void clearAuthInfos();
 384         /**
 385          * Adds authentication information to the LinphoneCore.
 386          * <br>This information will be used during all SIP transacations that require authentication.
 387          * @param info
 388          */
 389         void addAuthInfo(LinphoneAuthInfo info);
 390
 391         /**
 392          * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
 393          * @param destination
 394          * @return
 395          * @throws If no LinphoneAddress can be built from destination
 396          */
 397         public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
 398
 399         /**
 400          * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
 401          * @param uri
 402          */
 403         public LinphoneCall invite(String destination)throws LinphoneCoreException;
 404         /**
 405          * Initiates an outgoing call given a destination LinphoneAddress
 406          *<br>The LinphoneAddress can be constructed directly using {@link LinphoneCoreFactory#createLinphoneAddress} , or created {@link LinphoneCore#interpretUrl(String)}. .
 407          * @param to the destination of the call (sip address).
 408          * @return linphone call
 409          * @throws LinphoneCoreException if linphone call cannot be created
 410          */
 411         public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
 412         /**
 413          * Terminates a call.
 414          * @param aCall to be terminated
 415          */
 416         public void terminateCall(LinphoneCall aCall);
 417         /**
 418          * Declines an incoming call, providing a reason for declining it.
 419          * @param call the LinphoneCall, must be in the {@link LinphoneCall.State#IncomingReceived} state.
 420          * @param reason the reason for rejecting the call: {@link Reason#Declined}  or {@link Reason#Busy}
 421          */
 422         public void declineCall(LinphoneCall aCall, Reason reason);
 423         /**
 424          * Returns The LinphoneCall the current call if one is in call
 425          *
 426         **/
 427         public LinphoneCall getCurrentCall();
 428
 429         /**
 430          * get current call remote address in case of in/out call
 431          * @return null if no call engaged yet
 432          */
 433         public LinphoneAddress getRemoteAddress();
 434         /**
 435          *
 436          * @return  true if there is a call running or pending.
 437          */
 438         public boolean isIncall();
 439         /**
 440          *
 441          * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
 442          */
 443         public boolean isInComingInvitePending();
 444         /**
 445          * Main loop function. It is crucial that your application call it periodically.
 446          *
 447          *      #iterate() performs various backgrounds tasks:
 448          * <li>receiving of SIP messages
 449          * <li> handles timers and timeout
 450          * <li> performs registration to proxies
 451          * <li> authentication retries The application MUST call this function from periodically, in its main loop.
 452          * <br> Be careful that this function must be call from the same thread as other liblinphone methods. In not the case make sure all liblinphone calls are serialized with a mutex.
 453
 454          */
 455         public void iterate();
 456         /**
 457          * Accept an incoming call.
 458          *
 459          * Basically the application is notified of incoming calls within the
 460          * {@link LinphoneCoreListener#callState} listener method.
 461          * The application can later respond positively to the call using
 462          * this method.
 463          * @throws LinphoneCoreException
 464          */
 465         public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
 466
 467         /**
 468          * Accept an incoming call.
 469          *
 470          * Basically the application is notified of incoming calls within the
 471          * {@link LinphoneCoreListener#callState} listener method.
 472          * The application can later respond positively to the call using
 473          * this method.
 474          * @throws LinphoneCoreException
 475          */
 476         public void acceptCallWithParams(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
 477
 478         /**
 479          * Accept call modifications initiated by other end.
 480          *
 481          * Basically the application is notified of incoming calls within the
 482          * {@link LinphoneCoreListener#callState} listener method.
 483          * The application can later respond positively to the call using
 484          * this method.
 485          * @throws LinphoneCoreException
 486          */
 487         public void acceptCallUpdate(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
 488
 489
 490         /**
 491          * Prevent LinphoneCore from performing an automatic answer
 492          *
 493          * Basically the application is notified of incoming calls within the
 494          * {@link LinphoneCoreListener#callState} listener method.
 495          * The application can later respond positively to the call using
 496          * this method.
 497          * @throws LinphoneCoreException
 498          */
 499         public void deferCallUpdate(LinphoneCall aCall) throws LinphoneCoreException;
 500
 501         /**
 502          * @return a list of LinphoneCallLog
 503          */
 504         public LinphoneCallLog[] getCallLogs();
 505
 506         /**
 507          * This method is called by the application to notify the Linphone core library when network is reachable.
 508          * Calling this method with true trigger Linphone to initiate a registration process for all proxy
 509          * configuration with parameter register set to enable.
 510          * This method disable the automatic registration mode. It means you must call this method after each network state changes
 511          * @param network state
 512          *
 513          */
 514         public void setNetworkReachable(boolean isReachable);
 515         /**
 516          * Get network state has known by {@link LinphoneCore}
 517          * @return if false, there is no network connection.
 518          */
 519         public boolean isNetworkReachable();
 520         /**
 521          * destroy linphone core and free all underlying resources
 522          */
 523         public void destroy();
 524         /**
 525          * Allow to control play level before entering  sound card:
 526          * @param level in db
 527          */
 528         public void setPlaybackGain(float gain);
 529         /**
 530          * get play level before entering  sound card:
 531          * @return level in db
 532          */
 533         public float getPlaybackGain();
 534         /**
 535          * set play level
 536          * @param level [0..100]
 537          */
 538         public void setPlayLevel(int level);
 539         /**
 540          * get playback level [0..100];
 541          * -1 if not cannot be determined
 542          * @return
 543          */
 544         public int getPlayLevel();
 545         /**
 546          *  Mutes or unmutes the local microphone.
 547          * @param isMuted
 548          */
 549         void muteMic(boolean isMuted);
 550         /**
 551          *
 552          * @return true is mic is muted
 553          */
 554         boolean isMicMuted();
 555
 556         /**
 557          * Initiate a dtmf signal if in call
 558          * @param send dtmf ['0'..'9'] | '#', '*'
 559          */
 560         void sendDtmf(char number);
 561         /**
 562          * Initiate a dtmf signal to the speaker if not in call.
 563          * Sending of the DTMF is done in another function.
 564          * @param dtmf ['0'..'9'] | '#', '*'
 565          * @param duration in ms , -1 for unlimited
 566          */
 567         void playDtmf(char dtmf,int duration);
 568         /**
 569          * stop current dtmf
 570          */
 571         void stopDtmf();
 572
 573         /**
 574          * remove all call logs
 575          */
 576         void clearCallLogs();
 577
 578
 579
 580
 581         /**
 582          * Get payload type from mime type and clock rate
 583          *
 584          * This function searches in audio and video codecs for the given payload type name and clockrate.
 585          * @param mime payload mime type (I.E SPEEX, PCMU, VP8)
 586          * @param clockRate (I.E 8000, 16000, 90000, ...)
 587          * @param channels  number of channels
 588          * @return Returns null if not found.
 589          */
 590         PayloadType findPayloadType(String mime, int clockRate, int channels);
 591         /***
 592          * get payload type  from mime type and clock rate..
 593          * Same as @{link {@link #findPayloadType(String, int, int)} but ignoring channels params
 594          * @param mime payload mime type (I.E SPEEX, PCMU, VP8)
 595          * @param clockRate (I.E 8000, 16000, 90000, ...)
 596          * @return null if not found
 597          */
 598         PayloadType findPayloadType(String mime, int clockRate);
 599
 600         /***
 601          * get payload type  from mime type
 602          * Same as @{link {@link #findPayloadType(String, int, int)} but ignoring channels and clock rate params
 603          * @param mime payload mime type (I.E SPEEX, PCMU, VP8)
 604          * @return null if not found
 605          */
 606         PayloadType findPayloadType(String mime);
 607
 608         /**
 609          * Enable payload type
 610          * @param pt payload type to enable, can be retrieve from {@link #findPayloadType}
 611          * @param true if enabled
 612          * @exception LinphoneCoreException
 613          *
 614          */
 615         void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
 616         /**
 617          * Enables or disable echo cancellation.
 618          * @param enable
 619          */
 620         void enableEchoCancellation(boolean enable);
 621         /**
 622          * get EC status
 623          * @return true if echo cancellation is enabled.
 624          */
 625         boolean isEchoCancellationEnabled();
 626         /**
 627          * Get echo limiter status (another method of doing echo suppression, more brute force)
 628          * @return true if echo limiter is enabled
 629          */
 630         boolean isEchoLimiterEnabled();
 631         /**
 632          * Set transport ports linphone core will listen on
 633          * @param local transports ports used for signaling (TCP, UDP and TLS)
 634          */
 635         void setSignalingTransportPorts(Transports transports);
 636         /**Get
 637          * @return transports used for signaling (TCP, UDP, TLS)
 638          */
 639         Transports getSignalingTransportPorts();
 640
 641         /**
 642          * Assign a dscp value for the SIP socket.
 643          * DSCP is an IP packet field used to indicate the type of routing service to routers.
 644          * @param dscp
 645          */
 646         void setSipDscp(int dscp);
 647
 648         /**
 649          * Get DSCP used for SIP socket.
 650          * @return the DSCP value used for the SIP socket.
 651          */
 652         int getSipDscp();
 653
 654         /**
 655          * Activates or deactivates the speaker.
 656          * @param value
 657          */
 658         void enableSpeaker(boolean value);
 659         /**
 660          * Tells whether the speaker is activated.
 661          * @return true if speaker enabled, false otherwise
 662          */
 663         boolean isSpeakerEnabled();
 664         /**
 665          * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
 666          * @param lf LinphoenFriend to add
 667          * @throws LinphoneCoreException
 668          */
 669         void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
 670
 671         /**
 672          * Set my presence status
 673          * @param minute_away how long in away
 674          * @param status sip uri used to redirect call in state LinphoneStatusMoved
 675          */
 676         void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
 677         /**
 678          * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
 679          * @param to    destination address for messages
 680          *
 681          * @return {@link LinphoneChatRoom} where messaging can take place.
 682          */
 683         LinphoneChatRoom createChatRoom(String to);
 684         /**
 685          * Set the native video window id where the video is to be displayed.
 686          * On Android, it must be of type {@link AndroidVideoWindowImpl}
 687          * @param video window of type {@link AndroidVideoWindowImpl}
 688         **/
 689         void setVideoWindow(Object w);
 690         /**
 691          * Set the native video window id where the video preview is to be displayed.
 692          * On Android, it must of type {@link SurfaceView}
 693          * @param video window of type {@link SurfaceView}
 694         **/
 695         void setPreviewWindow(Object w);
 696         /**
 697          * Tells the core the device current orientation. This can be used by capture filters
 698          * on mobile devices to select between portrait/landscape mode and to produce properly
 699          * oriented images. The exact meaning of the value in rotation if left to each device
 700          * specific implementations.
 701          *@param rotation . Android supported values are 0, 90, 180 and 270.
 702          *
 703         **/
 704         void setDeviceRotation(int rotation);
 705         /**
 706          * Sets the active video device.
 707          *
 708          * @param id  of the video device as returned by {@link AndroidCameraConfiguration#retrieveCameras}
 709         **/
 710         void setVideoDevice(int id);
 711         /**
 712          * Returns the id of the currently active video device as found in {@link AndroidCameraConfiguration#retrieveCameras}.
 713         **/
 714         int getVideoDevice();
 715
 716         /**
 717          * Enables video globally.
 718          *
 719          *
 720          * This function does not have any effect during calls. It just indicates #LinphoneCore to
 721          * initiate future calls with video or not. The two boolean parameters indicate in which
 722          * direction video is enabled. Setting both to false disables video entirely.
 723          *
 724          * @param vcap_enabled indicates whether video capture is enabled
 725          * @param display_enabled indicates whether video display should be shown
 726          *
 727         **/
 728         void enableVideo(boolean vcap_enabled, boolean display_enabled);
 729         /**
 730          * Returns TRUE if video is enabled, FALSE otherwise.
 731          *
 732          ***/
 733         boolean isVideoEnabled();
 734
 735         /**
 736          * Specify a STUN server to help firewall traversal.
 737          * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
 738          */
 739         void setStunServer(String stun_server);
 740         /**
 741          * Get STUN server
 742          * @return stun server address if previously set.
 743          */
 744         String getStunServer();
 745
 746         /**
 747          * Sets policy regarding workarounding NATs
 748          * @param pol one of the FirewallPolicy members.
 749         **/
 750         void setFirewallPolicy(FirewallPolicy pol);
 751         /**
 752          * @return previously set firewall policy.
 753          */
 754         FirewallPolicy getFirewallPolicy();
 755         /**
 756          * Initiates an outgoing call given a destination LinphoneAddress
 757          *
 758          * @param addr the destination of the call {@link #LinphoneAddress }.
 759          * @param params call parameters {@link #LinphoneCallParams }
 760          *
 761          *<br>The LinphoneAddress can be constructed directly using {@link LinphoneCoreFactory#createLinphoneAddress} , or created {@link LinphoneCore#interpretUrl(String)}. .
 762          *
 763          * @return a {@link #LinphoneCall LinphoneCall} object
 764          * @throws LinphoneCoreException  in case of failure
 765         **/
 766         LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
 767         /**
 768          * Updates a running call according to supplied call parameters or parameters changed in the LinphoneCore.
 769          *
 770          * In this version this is limited to the following use cases:
 771          * - setting up/down the video stream according to the video parameter of the {@link LinphoneCallParams} (see {@link LinphoneCallParams#enableVideo} ).
 772          * - changing the size of the transmitted video after calling {@link LinphoneCore#setPreferredVideoSize(VideoSize)}
 773          *
 774          * In case no changes are requested through the {@link LinphoneCallParams} argument, then this argument can be omitted and set to null.
 775          * @param call the {@link LinphoneCall} to be updated
 776          * @param params the new  {@link  LinphoneCallParams call parameters} to use. (may be NULL)
 777          * @return 0 if successful, -1 otherwise.
 778         **/
 779         int updateCall(LinphoneCall call, LinphoneCallParams params);
 780         /**
 781          * Get default call parameters reflecting current linphone core configuration
 782          * @return  LinphoneCallParams
 783          */
 784         LinphoneCallParams createDefaultCallParameters();
 785
 786         /**
 787          * Sets the path to a wav file used for ringing.
 788          *
 789          * @param path The file must be a wav 16bit linear. Local ring is disabled if null
 790          */
 791         void setRing(String path);
 792         /**
 793          * gets the path to a wav file used for ringing.
 794          *
 795          * @return null if not set
 796          */
 797         String getRing();
 798
 799         /**
 800          * Sets file or folder containing trusted root CAs
 801          *
 802          * @param path path to file with multiple PEM certif or to folder with multiple PEM files
 803          */
 804         void setRootCA(String path);
 805
 806         void setUploadBandwidth(int bw);
 807         /**
 808          * Sets maximum available download bandwidth
 809          *
 810          *
 811          * This is IP bandwidth, in kbit/s.
 812          * This information is used signaled to other parties during
 813          * calls (within SDP messages) so that the remote end can have
 814          * sufficient knowledge to properly configure its audio & video
 815          * codec output bitrate to not overflow available bandwidth.
 816          *
 817          * @param bw the bandwidth in kbits/s, 0 for infinite
 818          */
 819         void setDownloadBandwidth(int bw);
 820
 821         /**
 822          * Sets audio packetization interval suggested for remote end.
 823          * @param ptime packetization interval in milliseconds
 824          */
 825         void setDownloadPtime(int ptime);
 826
 827         /**
 828          * Sets audio packetization interval sent to remote end.
 829          * @param ptime packetization interval in milliseconds
 830          */
 831         void setUploadPtime(int ptime);
 832         /**
 833          * Sets the preferred video size.
 834          *
 835          * This applies only to the stream that is captured and sent to the remote party,
 836          * since we accept all standard video size on the receive path.
 837          * @param vSize
 838          *
 839         **/
 840         void setPreferredVideoSize(VideoSize vSize);
 841         /**
 842          * get current preferred video size for sending.
 843          * @return  video size
 844          *
 845         **/
 846         VideoSize getPreferredVideoSize();
 847
 848         /**
 849          * Returns the currently supported audio codecs, as PayloadType elements
 850          * @return
 851          */
 852         PayloadType[] getAudioCodecs();
 853         /**
 854          * Returns the currently supported video codecs, as PayloadType elements
 855          * @return
 856          */
 857         PayloadType[] getVideoCodecs();
 858         /**
 859          * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
 860          */
 861         void enableKeepAlive(boolean enable);
 862         /**
 863          * get keep elive mode
 864          * @return true if enable
 865          */
 866         boolean isKeepAliveEnabled();
 867         /**
 868          * Start an echo calibration of the sound devices, in order to find adequate settings for the echo canceler automatically.
 869          * status is notified to {@link LinphoneCoreListener#ecCalibrationStatus(EcCalibratorStatus, int, Object)}
 870          * @param User object
 871          * @throws LinphoneCoreException if operation is still in progress;
 872         **/
 873         void startEchoCalibration(Object data) throws LinphoneCoreException;
 874
 875         /**
 876          * Returns true if echo calibration is recommended.
 877          * If the device has a builtin echo canceller or calibration value is already known, it will return false.
 878          */
 879         boolean needsEchoCalibration();
 880
 881         void enableIpv6(boolean enable);
 882         /**
 883          * @deprecated
 884          * @param i
 885          */
 886         void adjustSoftwareVolume(int i);
 887
 888         /**
 889          * Pauses a call. If a music file has been setup using {@link LinphoneCore#setPlayFile(String)},
 890          * this file will be played to the remote user.
 891          *
 892         **/
 893         boolean pauseCall(LinphoneCall call);
 894         /**
 895          * Resume a call.
 896         **/
 897         boolean resumeCall(LinphoneCall call);
 898         /**
 899          * Pause all currently running calls.
 900         **/
 901         boolean pauseAllCalls();
 902
 903         void setZrtpSecretsCache(String file);
 904         void enableEchoLimiter(boolean val);
 905
 906         /**
 907          * Indicates whether the local user is part of the conference.
 908         **/
 909         boolean isInConference();
 910         /**
 911          * Moves the local participant inside the conference.
 912          *
 913          * Makes the local participant to join the conference.
 914          * Typically, the local participant is by default always part of the conference when joining an active call into a conference.
 915          * However, by calling {@link #leaveConference()} and {@link #enterConference()} the application can decide to temporarily
 916          * move out and in the local participant from the conference.
 917          *
 918          * @returns true if successful
 919         **/
 920         boolean enterConference();
 921         /**
 922          * Moves the local participant out of the conference.
 923          * When the local participant is out of the conference, the remote participants can continue to talk normally.
 924         **/
 925         void leaveConference();
 926
 927         /**
 928          * Merge a call into a conference.
 929          *
 930          * If this is the first call that enters the conference, the virtual conference will be created automatically.
 931          * If the local user was actively part of the call (ie not in paused state), then the local user is automatically entered into the conference.
 932          * If the call was in paused state, then it is automatically resumed when entering into the conference.
 933          * @param call an established call, either in {@link LinphoneCall.State#StreamsRunning} or {@link LinphoneCall.State#Paused} state.
 934          *
 935         **/
 936         void addToConference(LinphoneCall call);
 937         /**
 938          * Remove a call from the conference.
 939          * @param call a call that has been previously merged into the conference.
 940          *
 941          * After removing the remote participant belonging to the supplied call, the call becomes a normal call in paused state.
 942          * If one single remote participant is left alone together with the local user in the conference after the removal, then the conference is
 943          * automatically transformed into a simple call in StreamsRunning state.
 944          * The conference's resources are then automatically destroyed.
 945          *
 946          * In other words, unless {@link #leaveConference()} is explicitely called, the last remote participant of a conference is automatically
 947          * put in a simple call in running state.
 948          *
 949          **/
 950         void removeFromConference(LinphoneCall call);
 951         /**
 952          * Add all calls into a conference.
 953          *
 954          * Merge all established calls (either in {@link LinphoneCall.State#StreamsRunning} or {@link LinphoneCall.State#Paused}) into a conference.
 955          *
 956         **/
 957         void addAllToConference();
 958
 959         /**
 960          * Terminates the conference and the calls associated with it.
 961          *
 962          * All the calls that were merged to the conference are terminated, and the conference resources are destroyed.
 963          *
 964         **/
 965         void terminateConference();
 966         /**
 967          * Returns the number of participants to the conference, including the local participant.
 968          *
 969          * Typically, after merging two calls into the conference, there is total of 3 participants:
 970          * the local participant (or local user), and two remote participants that were the destinations of the two previously establised calls.
 971          *
 972          * @returns the number of participants to the conference
 973         **/
 974         int getConferenceSize();
 975
 976         /**
 977          * Request recording of the conference into a supplied file path.
 978          * The format is wav.
 979          * @param path where to write recording file
 980         **/
 981         void startConferenceRecording(String path);
 982
 983         /**
 984          * Stop recording of the conference.
 985         **/
 986         void stopConferenceRecording();
 987         /**
 988          * Terminates all the calls.
 989          */
 990         void terminateAllCalls();
 991         /**
 992          * Returns all calls.
 993          * @return an array with all call currently handle by Linphone core
 994         **/
 995         LinphoneCall[] getCalls();
 996         /**
 997          * Get number of calls currently handled by Linphone core
 998          * @returns number of calls
 999          * */
1000         int getCallsNb();
1001
1002         /**
1003          * Performs a simple call transfer to the specified destination.
1004          *
1005          * @param call The current local call remains active and thus can be later paused or terminated.
1006          * @param  referTo The remote call party endpoint is expected to issue a new call to this specified destination.
1007         **/
1008         void transferCall(LinphoneCall call, String referTo);
1009         /**
1010          * Transfer a call to destination of another running call. This is used for "attended transfer" scenarios.
1011          * The transfered call is supposed to be in paused state, so that it is able to accept the transfer immediately.
1012          * The destination call is a call previously established to introduce the transfered person.
1013          * This method will send a transfer request to the transfered person. The phone of the transfered is then
1014          * expected to automatically call to the destination of the transfer. The receiver of the transfer will then automatically
1015          * close the call with us (the 'dest' call).
1016          * @param call a running call you want to transfer
1017          * @param dest a running call whose remote person will receive the transfer
1018         **/
1019         void transferCallToAnother(LinphoneCall callToTransfer, LinphoneCall destination);
1020         /**
1021          * Search from the list of current calls if a remote address match uri
1022          * @param uri which should match call remote uri
1023          * @return LinphoneCall or NULL is no match is found
1024          */
1025         LinphoneCall findCallFromUri(String uri);
1026         /**
1027          * Get the maximum number of simultaneous calls Linphone core can manage at a time. All new call above this limit are declined with a busy answer
1028          * @return max number of simultaneous calls
1029          */
1030         int getMaxCalls();
1031         /**
1032          * Set the maximum number of simultaneous calls Linphone core can manage at a time. All new call above this limit are declined with a busy answer
1033          * @param max number of simultaneous calls
1034          */
1035         void setMaxCalls(int max);
1036         /**
1037          * @deprecated
1038          * @param uri
1039          * @return
1040          */
1041         boolean isMyself(String uri);
1042
1043         /**
1044          * Use this method to check the calls state and forbid proposing actions
1045          * which could result in an active call.
1046          * Eg: don't start a new call if one is in outgoing ringing.
1047          * Eg: don't merge to conference either as it could result
1048          *     in two active calls (conference and accepted call).
1049          * @return
1050          */
1051         boolean soundResourcesLocked();
1052         /**
1053          * Returns whether given media encryption is supported by liblinphone.
1054          */
1055         boolean mediaEncryptionSupported(MediaEncryption menc);
1056         /**
1057          * set media encryption (rtp) to use
1058          * @params menc: MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
1059          */
1060         void setMediaEncryption(MediaEncryption menc);
1061         /**
1062          * return selected media encryption
1063          * @return MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
1064          */
1065         MediaEncryption getMediaEncryption();
1066 /**
1067          * Set media encryption required for outgoing calls
1068          */
1069         void setMediaEncryptionMandatory(boolean yesno);
1070         /**
1071          * @return if media encryption is required for outgoing calls
1072          */
1073         boolean isMediaEncryptionMandatory();
1074
1075         /**
1076          * @param path path to music file played to remote side when on hold.
1077          */
1078         void setPlayFile(String path);
1079         void tunnelEnable(boolean enable);
1080         void tunnelAutoDetect();
1081         void tunnelCleanServers();
1082         void tunnelSetHttpProxy(String proxy_host, int port, String username, String password);
1083         /**
1084          * @param host tunnel server ip address
1085          * @param port tunnel server tls port, recommended value is 443
1086          * @param udpMirrorPort remote port on the tunnel server side  used to test udp reachability
1087          * @param roundTripDelay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms
1088          */
1089         void tunnelAddServerAndMirror(String host, int port, int udpMirrorPort, int roundTripDelay);
1090
1091         boolean isTunnelAvailable();
1092         /**
1093          * Returns an unmodifiable list of entered proxy configurations.
1094          * @return list of proxy config
1095         **/
1096         LinphoneProxyConfig[] getProxyConfigList();
1097         /**
1098          * Sets the default policy for video.
1099          * This policy defines whether:
1100          * @param autoInitiate video shall be initiated by default for outgoing calls
1101          * @param autoAccept video shall be accepter by default for incoming calls
1102         **/
1103         void setVideoPolicy(boolean autoInitiate, boolean autoAccept);
1104         /** Set static picture to be used when "Static picture" is the video device
1105          * @param path to the static picture file
1106          * */
1107         void setStaticPicture(String path);
1108         /**
1109          * Sets the user agent string used in SIP messages.
1110          * @param user agent name
1111          * @param user agent version
1112         **/
1113         void setUserAgent(String name, String version);
1114         /**
1115          * Set the number of cores used for media processing
1116          * */
1117         void setCpuCount(int count);
1118
1119         /**
1120          * remove a call log
1121          */
1122         public void removeCallLog(LinphoneCallLog log);
1123
1124         /**
1125          * @return count of missed calls
1126          */
1127         public int getMissedCallsCount();
1128
1129         /**
1130          * Set missed calls count to zero
1131          */
1132         public void resetMissedCallsCount();
1133         /**
1134          * re-initiates registration if network is up.
1135          */
1136         public void refreshRegisters();
1137
1138         /**
1139          * return the version code of linphone core
1140          */
1141         public String getVersion();
1142
1143         /**
1144          * remove a linphone friend from linphone core and linphonerc
1145          */
1146         void removeFriend(LinphoneFriend lf);
1147
1148         /**
1149          * return a linphone friend (if exists) that matches the sip address
1150          */
1151         LinphoneFriend findFriendByAddress(String sipUri);
1152
1153         /**
1154          * Sets the UDP port used for audio streaming.
1155         **/
1156         void setAudioPort(int port);
1157
1158         /**
1159          * Sets the UDP port range from which to randomly select the port used for audio streaming.
1160          */
1161         void setAudioPortRange(int minPort, int maxPort);
1162
1163         /**
1164          * Assign a DSCP value to the audio RTP sockets.
1165          * @param dscp the DSCP value.
1166          * DSCP is an IP header field used to indicate a type of service to routers.
1167          */
1168         void setAudioDscp(int dscp);
1169
1170         /**
1171          * Return DSCP value used for the audio RTP sockets.
1172          * @return the DSCP value used for the audio RTP sockets.
1173          */
1174         int getAudioDscp();
1175
1176         /**
1177          * Sets the UDP port used for video streaming.
1178         **/
1179         void setVideoPort(int port);
1180
1181         /**
1182          * Sets the UDP port range from which to randomly select the port used for video streaming.
1183          */
1184         void setVideoPortRange(int minPort, int maxPort);
1185
1186         /**
1187          * Assign a DSCP value to the video RTP sockets.
1188          * @param dscp the DSCP value.
1189          * DSCP is an IP header field used to indicate a type of service to routers.
1190          */
1191         void setVideoDscp(int dscp);
1192
1193         /**
1194          * Return DSCP value used for the video RTP sockets.
1195          * @return the DSCP value used for the video RTP sockets.
1196          */
1197         int getVideoDscp();
1198
1199         /**
1200          * Set the incoming call timeout in seconds.
1201          * If an incoming call isn't answered for this timeout period, it is
1202          * automatically declined.
1203         **/
1204         void setIncomingTimeout(int timeout);
1205
1206         /**
1207          * Set the call timeout in seconds.
1208          * Once this time is elapsed (ringing included), the call is automatically hung up.
1209         **/
1210         void setInCallTimeout(int timeout);
1211         /**
1212          * Allow to control microphone level:
1213          * @param gain in db
1214         **/
1215         void setMicrophoneGain(float gain);
1216
1217         /**
1218          * Set username and display name to use if no LinphoneProxyConfig configured
1219          */
1220         void setPrimaryContact(String displayName, String username);
1221
1222         /**
1223          * Enable/Disable the use of SIP INFO for DTMFs
1224          */
1225         void setUseSipInfoForDtmfs(boolean use);
1226
1227         /**
1228          * Enable/Disable the use of inband DTMFs
1229          */
1230         void setUseRfc2833ForDtmfs(boolean use);
1231
1232         /**
1233          * @return returns LpConfig object to read/write to the config file: usefull if you wish to extend
1234          * the config file with your own sections
1235          */
1236         LpConfig getConfig();
1237
1238
1239         /**
1240          * Return the availability of uPnP.
1241          *
1242          * @return true if uPnP is available otherwise return false.
1243          */
1244         public boolean upnpAvailable();
1245
1246         /**
1247          * Return the internal state of uPnP.
1248          *
1249          * @return an UpnpState.
1250          */
1251         public UpnpState getUpnpState();
1252
1253         /**
1254          * Return the external ip address of router.
1255          * In some cases the uPnP can have an external ip address but not a usable uPnP
1256          * (state different of Ok).
1257          *
1258          * @return a null terminated string containing the external ip address. If the
1259          * the external ip address is not available return null.
1260          */
1261         public String getUpnpExternalIpaddress();
1262
1263 }