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 @SuppressWarnings("unchecked")
  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          * clear all added proxy configs
 184          */
 185         public void clearProxyConfigs();
 186         /**
 187          * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
 188          * @param proxyCfg
 189          * @throws LinphoneCoreException
 190          */
 191         public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
 192         /**
 193          * Sets the default proxy.
 194          *<br>
 195          * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
 196          * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
 197          * @param proxyCfg
 198          */
 199         public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
 200
 201         /**
 202          * get he default proxy configuration, that is the one used to determine the current identity.
 203          * @return null if no default proxy config
 204          */
 205         public LinphoneProxyConfig getDefaultProxyConfig() ;
 206
 207         /**
 208          * clear all the added auth info
 209          */
 210         void clearAuthInfos();
 211         /**
 212          * Adds authentication information to the LinphoneCore.
 213          * <br>This information will be used during all SIP transacations that require authentication.
 214          * @param info
 215          */
 216         void addAuthInfo(LinphoneAuthInfo info);
 217
 218         /**
 219          * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
 220          * @param destination
 221          * @return
 222          * @throws If no LinphoneAddress can be built from destination
 223          */
 224         public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
 225
 226         /**
 227          * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
 228          * @param uri
 229          */
 230         public LinphoneCall invite(String destination)throws LinphoneCoreException;
 231         /**
 232          * Initiates an outgoing call given a destination LinphoneAddress
 233          *<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.
 234          * @param to the destination of the call (sip address).
 235          * @return LinphoneCall
 236          * @throws LinphoneCoreException
 237          */
 238         public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
 239         /**
 240          * Terminates a call.
 241          * @param aCall to be terminated
 242          */
 243         public void terminateCall(LinphoneCall aCall);
 244         /**
 245          * Returns The LinphoneCall the current call if one is in call
 246          *
 247         **/
 248         public LinphoneCall getCurrentCall();
 249
 250         /**
 251          * get current call remote address in case of in/out call
 252          * @return null if no call engaged yet
 253          */
 254         public LinphoneAddress getRemoteAddress();
 255         /**
 256          *
 257          * @return  TRUE if there is a call running or pending.
 258          */
 259         public boolean isIncall();
 260         /**
 261          *
 262          * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
 263          */
 264         public boolean isInComingInvitePending();
 265         /**
 266          * Main loop function. It is crucial that your application call it periodically.
 267          *
 268          *      #iterate() performs various backgrounds tasks:
 269          * <li>receiving of SIP messages
 270          * <li> handles timers and timeout
 271          * <li> performs registration to proxies
 272          * <li> authentication retries The application MUST call this function from periodically, in its main loop.
 273          * <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.
 274
 275          */
 276         public void iterate();
 277         /**
 278          * Accept an incoming call.
 279          *
 280          * Basically the application is notified of incoming calls within the
 281          * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
 282          * The application can later respond positively to the call using
 283          * this method.
 284          * @throws LinphoneCoreException
 285          */
 286         public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
 287
 288
 289         /**
 290          * @return a list of LinphoneCallLog
 291          */
 292         public Vector getCallLogs();
 293
 294         /**
 295          * This method is called by the application to notify the Linphone core library when network is reachable.
 296          * Calling this method with true trigger Linphone to initiate a registration process for all proxy
 297          * configuration with parameter register set to enable.
 298          * This method disable the automatic registration mode. It means you must call this method after each network state changes
 299          * @param network state
 300          *
 301          */
 302         public void setNetworkReachable(boolean isReachable);
 303         /**
 304          *
 305          * @return if false, there is no network connection.
 306          */
 307         public boolean isNetworkReachable();
 308         /**
 309          * destroy linphone core and free all underlying resources
 310          */
 311         public void destroy();
 312         /**
 313          * Allow to control play level before entering  sound card:
 314          * @param level in db
 315          */
 316         public void setPlaybackGain(float gain);
 317         /**
 318          * get play level before entering  sound card:
 319          * @return level in db
 320          */
 321         public float getPlaybackGain();
 322         /**
 323          * set play level
 324          * @param level [0..100]
 325          */
 326         public void setPlayLevel(int level);
 327         /**
 328          * get playback level [0..100];
 329          * -1 if not cannot be determined
 330          * @return
 331          */
 332         public int getPlayLevel();
 333         /**
 334          *  Mutes or unmutes the local microphone.
 335          * @param isMuted
 336          */
 337         public void muteMic(boolean isMuted);
 338         /**
 339          *
 340          * @return true is mic is muted
 341          */
 342         public boolean isMicMuted();
 343
 344         /**
 345          * Initiate a dtmf signal if in call
 346          * @param number
 347          */
 348         public void sendDtmf(char number);
 349         /**
 350          * Initiate a dtmf signal to the speqker if not in call
 351          * @param number
 352          * @param duration in ms , -1 for unlimited
 353          */
 354         public void playDtmf(char number,int duration);
 355         /**
 356          * stop current dtmf
 357          */
 358         public void stopDtmf();
 359
 360         /**
 361          * remove all call logs
 362          */
 363         public void clearCallLogs();
 364         /***
 365          * get payload type  from mime type an clock rate
 366          *
 367          * return null if not found
 368          */
 369         public PayloadType findPayloadType(String mime,int clockRate);
 370         /**
 371          * not implemented yet
 372          * @param pt
 373          * @param enable
 374          * @throws LinphoneCoreException
 375          */
 376         public void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
 377         /**
 378          * Enables or disable echo cancellation.
 379          * @param enable
 380          */
 381         public void enableEchoCancellation(boolean enable);
 382         /**
 383          * get EC status
 384          * @return true if echo cancellation is enabled.
 385          */
 386         public boolean isEchoCancellationEnabled();
 387         /**
 388          * not implemented yet
 389          * @param aTransport
 390          */
 391         public void setSignalingTransport(Transport aTransport);
 392         /**
 393          * not implemented
 394          * @param value
 395          */
 396         public void enableSpeaker(boolean value);
 397         /**
 398          * not implemented
 399          * @return
 400          */
 401         public boolean isSpeakerEnabled();
 402         /**
 403          * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
 404          * @param lf LinphoenFriend to add
 405          * @throws LinphoneCoreException
 406          */
 407         void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
 408
 409         /**
 410          * Set my presence status
 411          * @param minute_away how long in away
 412          * @param status sip uri used to redirect call in state LinphoneStatusMoved
 413          */
 414         void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
 415         /**
 416          * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
 417          * @param to    destination address for messages
 418          *
 419          * @return {@link LinphoneChatRoom} where messaging can take place.
 420          */
 421         LinphoneChatRoom createChatRoom(String to);
 422
 423         public void setVideoWindow(Object w);
 424         public void setPreviewWindow(Object w);
 425         /**
 426          * Enables video globally.
 427          *
 428          *
 429          * This function does not have any effect during calls. It just indicates #LinphoneCore to
 430          * initiate future calls with video or not. The two boolean parameters indicate in which
 431          * direction video is enabled. Setting both to false disables video entirely.
 432          *
 433          * @param vcap_enabled indicates whether video capture is enabled
 434          * @param display_enabled indicates whether video display should be shown
 435          *
 436         **/
 437         void enableVideo(boolean vcap_enabled, boolean display_enabled);
 438         /**
 439          * Returns TRUE if video is enabled, FALSE otherwise.
 440          *
 441          ***/
 442         boolean isVideoEnabled();
 443
 444         /**
 445          * Specify a STUN server to help firewall traversal.
 446          * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
 447          */
 448         public void setStunServer(String stun_server);
 449         /**
 450          * @return stun server address if previously set.
 451          */
 452         public String getStunServer();
 453
 454         /**
 455          * Sets policy regarding workarounding NATs
 456          * @param pol one of the FirewallPolicy members.
 457         **/
 458         public void setFirewallPolicy(FirewallPolicy pol);
 459         /**
 460          * @return previously set firewall policy.
 461          */
 462         public FirewallPolicy getFirewallPolicy();
 463
 464         public LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
 465
 466         public int updateCall(LinphoneCall call, LinphoneCallParams params);
 467
 468         public LinphoneCallParams createDefaultCallParameters();
 469
 470         /**
 471          * Sets the path to a wav file used for ringing.
 472          *
 473          * @param path The file must be a wav 16bit linear. Local ring is disabled if null
 474          */
 475         public void setRing(String path);
 476         /**
 477          * gets the path to a wav file used for ringing.
 478          *
 479          * @param null if not set
 480          */
 481         public String getRing();
 482         public void setUploadBandwidth(int bw);
 483
 484         public void setDownloadBandwidth(int bw);
 485
 486         public void setPreferredVideoSize(VideoSize vSize);
 487
 488         public VideoSize getPreferredVideoSize();
 489
 490         public PayloadType[] listVideoCodecs();
 491         /**
 492          * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
 493          */
 494         void enableKeepAlive(boolean enable);
 495         /**
 496          * get keep elive mode
 497          * @return true if enable
 498          */
 499         boolean isKeepAliveEnabled();
 500 }