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