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