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
  22 import java.util.List;
  23 import java.util.Vector;
  24
  25 /**
  26  * Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.
  27  *
  28  */
  29
  30 public interface LinphoneCore {
  31         /**
  32          * linphone core states
  33          */
  34         static public class GlobalState {
  35                 @SuppressWarnings("unchecked")
  36                 static private Vector values = new Vector();
  37                 /**
  38                  * Off
  39                  */
  40                 static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");
  41                 /**
  42                  * Startup
  43                  */
  44                 static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
  45                 /**
  46                  * On
  47                  */
  48                 static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
  49                 /**
  50                  * Shutdown
  51                  */
  52                 static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
  53
  54                 private final int mValue;
  55                 private final String mStringValue;
  56
  57                 @SuppressWarnings("unchecked")
  58                 private GlobalState(int value,String stringValue) {
  59                         mValue = value;
  60                         values.addElement(this);
  61                         mStringValue=stringValue;
  62                 }
  63                 public static GlobalState fromInt(int value) {
  64
  65                         for (int i=0; i<values.size();i++) {
  66                                 GlobalState state = (GlobalState) values.elementAt(i);
  67                                 if (state.mValue == value) return state;
  68                         }
  69                         throw new RuntimeException("state not found ["+value+"]");
  70                 }
  71                 public String toString() {
  72                         return mStringValue;
  73                 }
  74         }
  75         /**
  76          * Describes proxy registration states.
  77          *
  78          */
  79         static public class RegistrationState {
  80                 @SuppressWarnings("unchecked")
  81                 private static Vector values = new Vector();
  82                 /**
  83                  * None
  84                  */
  85                 public static RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");
  86                 /**
  87                  * In Progress
  88                  */
  89                 public static RegistrationState RegistrationProgress  = new RegistrationState(1,"RegistrationProgress");
  90                 /**
  91                  * Ok
  92                  */
  93                 public static RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
  94                 /**
  95                  * Cleared
  96                  */
  97                 public static RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
  98                 /**
  99                  * Failed
 100                  */
 101                 public static RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
 102                 private final int mValue;
 103                 private final String mStringValue;
 104
 105                 @SuppressWarnings("unchecked")
 106                 private RegistrationState(int value,String stringValue) {
 107                         mValue = value;
 108                         values.addElement(this);
 109                         mStringValue=stringValue;
 110                 }
 111                 public static RegistrationState fromInt(int value) {
 112
 113                         for (int i=0; i<values.size();i++) {
 114                                 RegistrationState state = (RegistrationState) values.elementAt(i);
 115                                 if (state.mValue == value) return state;
 116                         }
 117                         throw new RuntimeException("state not found ["+value+"]");
 118                 }
 119                 public String toString() {
 120                         return mStringValue;
 121                 }
 122         }
 123         /**
 124          * Describes firewall policy.
 125          *
 126          */
 127         static public class FirewallPolicy {
 128                 @SuppressWarnings("unchecked")
 129                 static private Vector values = new Vector();
 130                 /**
 131                  * No firewall is assumed.
 132                  */
 133                 static public FirewallPolicy NoFirewall = new FirewallPolicy(0,"NoFirewall");
 134                 /**
 135                  * Use NAT address (discouraged)
 136                  */
 137                 static public FirewallPolicy UseNatAddress  = new FirewallPolicy(1,"UseNatAddress");
 138                 /**
 139                  * Use stun server to discover RTP addresses and ports.
 140                  */
 141                 static public FirewallPolicy UseStun = new FirewallPolicy(2,"UseStun");
 142
 143                 private final int mValue;
 144                 private final String mStringValue;
 145
 146                 @SuppressWarnings("unchecked")
 147                 private FirewallPolicy(int value,String stringValue) {
 148                         mValue = value;
 149                         values.addElement(this);
 150                         mStringValue=stringValue;
 151                 }
 152                 public static FirewallPolicy fromInt(int value) {
 153
 154                         for (int i=0; i<values.size();i++) {
 155                                 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
 156                                 if (state.mValue == value) return state;
 157                         }
 158                         throw new RuntimeException("state not found ["+value+"]");
 159                 }
 160                 public String toString() {
 161                         return mStringValue;
 162                 }
 163                 public int value(){
 164                         return mValue;
 165                 }
 166         }
 167
 168         /**
 169          * Signaling transports ports.
 170          */
 171         static public class Transports {
 172                 public int udp;
 173                 public int tcp;
 174                 public int tls;
 175
 176                 public Transports() {};
 177                 public Transports(Transports t) {
 178                         this.udp = t.udp;
 179                         this.tcp = t.tcp;
 180                         this.tls = t.tls;
 181                 }
 182         }
 183         /**
 184          *      EC Calibrator Status
 185          */
 186         static public class EcCalibratorStatus {
 187                 @SuppressWarnings("unchecked")
 188                 static private Vector values = new Vector();
 189                 public static final int IN_PROGRESS_STATUS=0;
 190                 public static final int DONE_STATUS=1;
 191                 public static final int FAILED_STATUS=2;
 192                 /**
 193                  * Calibration in progress
 194                  */
 195                 static public EcCalibratorStatus InProgress = new EcCalibratorStatus(IN_PROGRESS_STATUS,"InProgress");
 196                 /**
 197                  * Calibration done
 198                  */
 199                 static public EcCalibratorStatus Done  = new EcCalibratorStatus(DONE_STATUS,"Done");
 200                 /**
 201                  * Calibration in progress
 202                  */
 203                 static public EcCalibratorStatus Failed = new EcCalibratorStatus(FAILED_STATUS,"Failed");
 204
 205                 private final int mValue;
 206                 private final String mStringValue;
 207
 208                 @SuppressWarnings("unchecked")
 209                 private EcCalibratorStatus(int value,String stringValue) {
 210                         mValue = value;
 211                         values.addElement(this);
 212                         mStringValue=stringValue;
 213                 }
 214                 public static EcCalibratorStatus fromInt(int value) {
 215
 216                         for (int i=0; i<values.size();i++) {
 217                                 EcCalibratorStatus status = (EcCalibratorStatus) values.elementAt(i);
 218                                 if (status.mValue == value) return status;
 219                         }
 220                         throw new RuntimeException("status not found ["+value+"]");
 221                 }
 222                 public String toString() {
 223                         return mStringValue;
 224                 }
 225                 public int value(){
 226                         return mValue;
 227                 }
 228         }
 229         /**
 230          * clear all added proxy configs
 231          */
 232         public void clearProxyConfigs();
 233         /**
 234          * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
 235          * @param proxyCfg
 236          * @throws LinphoneCoreException
 237          */
 238         public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
 239         /**
 240          * Sets the default proxy.
 241          *<br>
 242          * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
 243          * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
 244          * @param proxyCfg
 245          */
 246         public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
 247
 248         /**
 249          * get he default proxy configuration, that is the one used to determine the current identity.
 250          * @return null if no default proxy config
 251          */
 252         public LinphoneProxyConfig getDefaultProxyConfig() ;
 253
 254         /**
 255          * clear all the added auth info
 256          */
 257         void clearAuthInfos();
 258         /**
 259          * Adds authentication information to the LinphoneCore.
 260          * <br>This information will be used during all SIP transacations that require authentication.
 261          * @param info
 262          */
 263         void addAuthInfo(LinphoneAuthInfo info);
 264
 265         /**
 266          * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
 267          * @param destination
 268          * @return
 269          * @throws If no LinphoneAddress can be built from destination
 270          */
 271         public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
 272
 273         /**
 274          * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
 275          * @param uri
 276          */
 277         public LinphoneCall invite(String destination)throws LinphoneCoreException;
 278         /**
 279          * Initiates an outgoing call given a destination LinphoneAddress
 280          *<br>The LinphoneAddress can be constructed directly using linphone_address_new(), or created by linphone_core_interpret_url(). The application doesn't own a reference to the returned LinphoneCall object. Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
 281          * @param to the destination of the call (sip address).
 282          * @return LinphoneCall
 283          * @throws LinphoneCoreException
 284          */
 285         public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
 286         /**
 287          * Terminates a call.
 288          * @param aCall to be terminated
 289          */
 290         public void terminateCall(LinphoneCall aCall);
 291         /**
 292          * Returns The LinphoneCall the current call if one is in call
 293          *
 294         **/
 295         public LinphoneCall getCurrentCall();
 296
 297         /**
 298          * get current call remote address in case of in/out call
 299          * @return null if no call engaged yet
 300          */
 301         public LinphoneAddress getRemoteAddress();
 302         /**
 303          *
 304          * @return  TRUE if there is a call running or pending.
 305          */
 306         public boolean isIncall();
 307         /**
 308          *
 309          * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
 310          */
 311         public boolean isInComingInvitePending();
 312         /**
 313          * Main loop function. It is crucial that your application call it periodically.
 314          *
 315          *      #iterate() performs various backgrounds tasks:
 316          * <li>receiving of SIP messages
 317          * <li> handles timers and timeout
 318          * <li> performs registration to proxies
 319          * <li> authentication retries The application MUST call this function from periodically, in its main loop.
 320          * <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.
 321
 322          */
 323         public void iterate();
 324         /**
 325          * Accept an incoming call.
 326          *
 327          * Basically the application is notified of incoming calls within the
 328          * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
 329          * The application can later respond positively to the call using
 330          * this method.
 331          * @throws LinphoneCoreException
 332          */
 333         public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
 334
 335
 336         /**
 337          * @return a list of LinphoneCallLog
 338          */
 339         @SuppressWarnings("unchecked")
 340         public List getCallLogs();
 341
 342         /**
 343          * This method is called by the application to notify the Linphone core library when network is reachable.
 344          * Calling this method with true trigger Linphone to initiate a registration process for all proxy
 345          * configuration with parameter register set to enable.
 346          * This method disable the automatic registration mode. It means you must call this method after each network state changes
 347          * @param network state
 348          *
 349          */
 350         public void setNetworkReachable(boolean isReachable);
 351         /**
 352          *
 353          * @return if false, there is no network connection.
 354          */
 355         public boolean isNetworkReachable();
 356         /**
 357          * destroy linphone core and free all underlying resources
 358          */
 359         public void destroy();
 360         /**
 361          * Allow to control play level before entering  sound card:
 362          * @param level in db
 363          */
 364         public void setPlaybackGain(float gain);
 365         /**
 366          * get play level before entering  sound card:
 367          * @return level in db
 368          */
 369         public float getPlaybackGain();
 370         /**
 371          * set play level
 372          * @param level [0..100]
 373          */
 374         public void setPlayLevel(int level);
 375         /**
 376          * get playback level [0..100];
 377          * -1 if not cannot be determined
 378          * @return
 379          */
 380         public int getPlayLevel();
 381         /**
 382          *  Mutes or unmutes the local microphone.
 383          * @param isMuted
 384          */
 385         void muteMic(boolean isMuted);
 386         /**
 387          *
 388          * @return true is mic is muted
 389          */
 390         boolean isMicMuted();
 391
 392         /**
 393          * Initiate a dtmf signal if in call
 394          * @param number
 395          */
 396         void sendDtmf(char number);
 397         /**
 398          * Initiate a dtmf signal to the speaker if not in call.
 399          * Sending of the DTMF is done in another function.
 400          * @param number
 401          * @param duration in ms , -1 for unlimited
 402          */
 403         void playDtmf(char number,int duration);
 404         /**
 405          * stop current dtmf
 406          */
 407         void stopDtmf();
 408
 409         /**
 410          * remove all call logs
 411          */
 412         void clearCallLogs();
 413         /***
 414          * get payload type  from mime type an clock rate
 415          *
 416          * return null if not found
 417          */
 418         PayloadType findPayloadType(String mime,int clockRate);
 419         /**
 420          * not implemented yet
 421          * @param pt
 422          * @param enable
 423          * @throws LinphoneCoreException
 424          */
 425         void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
 426         /**
 427          * Enables or disable echo cancellation.
 428          * @param enable
 429          */
 430         void enableEchoCancellation(boolean enable);
 431         /**
 432          * get EC status
 433          * @return true if echo cancellation is enabled.
 434          */
 435         boolean isEchoCancellationEnabled();
 436         /**
 437          * @param transports used for signaling (TCP, UDP and TLS)
 438          */
 439         void setSignalingTransportPorts(Transports transports);
 440         /**
 441          * @return transports used for signaling (TCP, UDP, TLS)
 442          */
 443         Transports getSignalingTransportPorts();
 444         /**
 445          * not implemented
 446          * @param value
 447          */
 448         void enableSpeaker(boolean value);
 449         /**
 450          * not implemented
 451          * @return
 452          */
 453         boolean isSpeakerEnabled();
 454         /**
 455          * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
 456          * @param lf LinphoenFriend to add
 457          * @throws LinphoneCoreException
 458          */
 459         void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
 460
 461         /**
 462          * Set my presence status
 463          * @param minute_away how long in away
 464          * @param status sip uri used to redirect call in state LinphoneStatusMoved
 465          */
 466         void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
 467         /**
 468          * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
 469          * @param to    destination address for messages
 470          *
 471          * @return {@link LinphoneChatRoom} where messaging can take place.
 472          */
 473         LinphoneChatRoom createChatRoom(String to);
 474
 475         void setVideoWindow(Object w);
 476         void setPreviewWindow(Object w);
 477         void setDeviceRotation(int rotation);
 478
 479         void setVideoDevice(int id);
 480         int getVideoDevice();
 481
 482         /**
 483          * Enables video globally.
 484          *
 485          *
 486          * This function does not have any effect during calls. It just indicates #LinphoneCore to
 487          * initiate future calls with video or not. The two boolean parameters indicate in which
 488          * direction video is enabled. Setting both to false disables video entirely.
 489          *
 490          * @param vcap_enabled indicates whether video capture is enabled
 491          * @param display_enabled indicates whether video display should be shown
 492          *
 493         **/
 494         void enableVideo(boolean vcap_enabled, boolean display_enabled);
 495         /**
 496          * Returns TRUE if video is enabled, FALSE otherwise.
 497          *
 498          ***/
 499         boolean isVideoEnabled();
 500
 501         /**
 502          * Specify a STUN server to help firewall traversal.
 503          * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
 504          */
 505         void setStunServer(String stun_server);
 506         /**
 507          * @return stun server address if previously set.
 508          */
 509         String getStunServer();
 510
 511         /**
 512          * Sets policy regarding workarounding NATs
 513          * @param pol one of the FirewallPolicy members.
 514         **/
 515         void setFirewallPolicy(FirewallPolicy pol);
 516         /**
 517          * @return previously set firewall policy.
 518          */
 519         FirewallPolicy getFirewallPolicy();
 520
 521         LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
 522
 523         int updateCall(LinphoneCall call, LinphoneCallParams params);
 524
 525         LinphoneCallParams createDefaultCallParameters();
 526
 527         /**
 528          * Sets the path to a wav file used for ringing.
 529          *
 530          * @param path The file must be a wav 16bit linear. Local ring is disabled if null
 531          */
 532         void setRing(String path);
 533         /**
 534          * gets the path to a wav file used for ringing.
 535          *
 536          * @param null if not set
 537          */
 538         String getRing();
 539
 540         /**
 541          * Sets file or folder containing trusted root CAs
 542          *
 543          * @param path path to file with multiple PEM certif or to folder with multiple PEM files
 544          */
 545         void setRootCA(String path);
 546
 547         void setUploadBandwidth(int bw);
 548
 549         void setDownloadBandwidth(int bw);
 550
 551         /**
 552          * Sets audio packetization interval suggested for remote end.
 553          * @param ptime packetization interval in milliseconds
 554          */
 555         void setDownloadPtime(int ptime);
 556
 557         /**
 558          * Sets audio packetization interval sent to remote end.
 559          * @param ptime packetization interval in milliseconds
 560          */
 561         void setUploadPtime(int ptime);
 562
 563         void setPreferredVideoSize(VideoSize vSize);
 564
 565         VideoSize getPreferredVideoSize();
 566
 567         /**
 568          * Returns the currently supported audio codecs, as PayloadType elements
 569          * @return
 570          */
 571         PayloadType[] getAudioCodecs();
 572         /**
 573          * Returns the currently supported video codecs, as PayloadType elements
 574          * @return
 575          */
 576         PayloadType[] getVideoCodecs();
 577         /**
 578          * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
 579          */
 580         void enableKeepAlive(boolean enable);
 581         /**
 582          * get keep elive mode
 583          * @return true if enable
 584          */
 585         boolean isKeepAliveEnabled();
 586         /**
 587          * Start an echo calibration of the sound devices, in order to find adequate settings for the echo canceler automatically.
 588          * status is notified to {@link LinphoneCoreListener#ecCalibrationStatus(EcCalibratorStatus, int, Object)}
 589          * @param User object
 590          * @throws LinphoneCoreException if operation is still in progress;
 591         **/
 592         void startEchoCalibration(Object data) throws LinphoneCoreException;
 593
 594         void enableIpv6(boolean enable);
 595         void adjustSoftwareVolume(int i);
 596
 597         boolean pauseCall(LinphoneCall call);
 598         boolean resumeCall(LinphoneCall call);
 599         boolean pauseAllCalls();
 600
 601         void setZrtpSecretsCache(String file);
 602         void enableEchoLimiter(boolean val);
 603
 604         boolean isInConference();
 605         void enterConference();
 606         void leaveConference();
 607
 608         void addToConference(LinphoneCall call);
 609         void addAllToConference();
 610         void removeFromConference(LinphoneCall call);
 611
 612         void terminateConference();
 613         int getConferenceSize();
 614
 615         void terminateAllCalls();
 616         @SuppressWarnings("unchecked") List getCalls();
 617         int getCallsNb();
 618
 619
 620         void transferCall(LinphoneCall call, String referTo);
 621         void transferCallToAnother(LinphoneCall callToTransfer, LinphoneCall destination);
 622
 623         LinphoneCall findCallFromUri(String uri);
 624
 625         void setMediaEncryption(String menc);
 626         String getMediaEncryption();
 627
 628         void setMediaEncryptionMandatory(boolean yesno);
 629         boolean isMediaEncryptionMandatory();
 630 }