3 Copyright (C) 2010 Belledonne Communications, Grenoble, France
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.
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.
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.
19 package org.linphone.core;
21 import java.util.Vector;
24 * Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.
28 public interface LinphoneCore {
30 * linphone core states
32 static public class GlobalState {
34 static private Vector values = new Vector();
38 static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");
42 static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
46 static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
50 static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
52 private final int mValue;
53 private final String mStringValue;
56 private GlobalState(int value,String stringValue) {
58 values.addElement(this);
59 mStringValue=stringValue;
61 public static GlobalState fromInt(int value) {
63 for (int i=0; i<values.size();i++) {
64 GlobalState state = (GlobalState) values.elementAt(i);
65 if (state.mValue == value) return state;
67 throw new RuntimeException("state not found ["+value+"]");
69 public String toString() {
74 * Describes proxy registration states.
77 static public class RegistrationState {
79 private static Vector values = new Vector();
83 public static RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");
87 public static RegistrationState RegistrationProgress = new RegistrationState(1,"RegistrationProgress");
91 public static RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
95 public static RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
99 public static RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
100 private final int mValue;
101 private final String mStringValue;
104 private RegistrationState(int value,String stringValue) {
106 values.addElement(this);
107 mStringValue=stringValue;
109 public static RegistrationState fromInt(int value) {
111 for (int i=0; i<values.size();i++) {
112 RegistrationState state = (RegistrationState) values.elementAt(i);
113 if (state.mValue == value) return state;
115 throw new RuntimeException("state not found ["+value+"]");
117 public String toString() {
122 * Describes firewall policy.
125 static public class FirewallPolicy {
127 static private Vector values = new Vector();
129 * No firewall is assumed.
131 static public FirewallPolicy NoFirewall = new FirewallPolicy(0,"NoFirewall");
133 * Use NAT address (discouraged)
135 static public FirewallPolicy UseNatAddress = new FirewallPolicy(1,"UseNatAddress");
137 * Use stun server to discover RTP addresses and ports.
139 static public FirewallPolicy UseStun = new FirewallPolicy(2,"UseStun");
143 static public FirewallPolicy UseIce = new FirewallPolicy(3,"UseIce");
145 private final int mValue;
146 private final String mStringValue;
149 private FirewallPolicy(int value,String stringValue) {
151 values.addElement(this);
152 mStringValue=stringValue;
154 public static FirewallPolicy fromInt(int value) {
156 for (int i=0; i<values.size();i++) {
157 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
158 if (state.mValue == value) return state;
160 throw new RuntimeException("state not found ["+value+"]");
162 public String toString() {
171 * Signaling transports ports.
173 static public class Transports {
178 public Transports() {};
179 public Transports(Transports t) {
184 public String toString() {
185 return "udp["+udp+"] tcp["+tcp+"] tls["+tls+"]";
189 * Media (RTP) encryption enum-like.
192 static public final class MediaEncryption {
194 static private Vector values = new Vector();
198 static public final MediaEncryption None = new MediaEncryption(0,"None");
202 static public final MediaEncryption SRTP = new MediaEncryption(1,"SRTP");
206 static public final MediaEncryption ZRTP = new MediaEncryption(2,"ZRTP");
207 protected final int mValue;
208 private final String mStringValue;
211 private MediaEncryption(int value,String stringValue) {
213 values.addElement(this);
214 mStringValue=stringValue;
216 public static MediaEncryption fromInt(int value) {
218 for (int i=0; i<values.size();i++) {
219 MediaEncryption menc = (MediaEncryption) values.elementAt(i);
220 if (menc.mValue == value) return menc;
222 throw new RuntimeException("MediaEncryption not found ["+value+"]");
224 public String toString() {
229 * EC Calibrator Status
231 static public class EcCalibratorStatus {
233 static private Vector values = new Vector();
234 /* Do not change the values of these constants or the strings associated with them to prevent breaking
235 the collection of echo canceller calibration results during the wizard! */
236 public static final int IN_PROGRESS_STATUS=0;
237 public static final int DONE_STATUS=1;
238 public static final int FAILED_STATUS=2;
239 public static final int DONE_NO_ECHO_STATUS=3;
241 * Calibration in progress
243 static public EcCalibratorStatus InProgress = new EcCalibratorStatus(IN_PROGRESS_STATUS,"InProgress");
245 * Calibration done that produced an echo delay measure
247 static public EcCalibratorStatus Done = new EcCalibratorStatus(DONE_STATUS,"Done");
251 static public EcCalibratorStatus Failed = new EcCalibratorStatus(FAILED_STATUS,"Failed");
253 * Calibration done with no echo detected
255 static public EcCalibratorStatus DoneNoEcho = new EcCalibratorStatus(DONE_NO_ECHO_STATUS, "DoneNoEcho");
257 private final int mValue;
258 private final String mStringValue;
261 private EcCalibratorStatus(int value,String stringValue) {
263 values.addElement(this);
264 mStringValue=stringValue;
266 public static EcCalibratorStatus fromInt(int value) {
268 for (int i=0; i<values.size();i++) {
269 EcCalibratorStatus status = (EcCalibratorStatus) values.elementAt(i);
270 if (status.mValue == value) return status;
272 throw new RuntimeException("status not found ["+value+"]");
274 public String toString() {
282 * clear all added proxy configs
284 public void clearProxyConfigs();
286 * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
288 * @throws LinphoneCoreException
290 public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
292 * Sets the default proxy.
294 * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
295 * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
298 public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
301 * get he default proxy configuration, that is the one used to determine the current identity.
302 * @return null if no default proxy config
304 public LinphoneProxyConfig getDefaultProxyConfig() ;
307 * clear all the added auth info
309 void clearAuthInfos();
311 * Adds authentication information to the LinphoneCore.
312 * <br>This information will be used during all SIP transacations that require authentication.
315 void addAuthInfo(LinphoneAuthInfo info);
318 * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
321 * @throws If no LinphoneAddress can be built from destination
323 public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
326 * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
329 public LinphoneCall invite(String destination)throws LinphoneCoreException;
331 * Initiates an outgoing call given a destination LinphoneAddress
332 *<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.
333 * @param to the destination of the call (sip address).
334 * @return LinphoneCall
335 * @throws LinphoneCoreException
337 public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
340 * @param aCall to be terminated
342 public void terminateCall(LinphoneCall aCall);
344 * Returns The LinphoneCall the current call if one is in call
347 public LinphoneCall getCurrentCall();
350 * get current call remote address in case of in/out call
351 * @return null if no call engaged yet
353 public LinphoneAddress getRemoteAddress();
356 * @return TRUE if there is a call running or pending.
358 public boolean isIncall();
361 * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
363 public boolean isInComingInvitePending();
365 * Main loop function. It is crucial that your application call it periodically.
367 * #iterate() performs various backgrounds tasks:
368 * <li>receiving of SIP messages
369 * <li> handles timers and timeout
370 * <li> performs registration to proxies
371 * <li> authentication retries The application MUST call this function from periodically, in its main loop.
372 * <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.
375 public void iterate();
377 * Accept an incoming call.
379 * Basically the application is notified of incoming calls within the
380 * {@link LinphoneCoreListener#callState} listener method.
381 * The application can later respond positively to the call using
383 * @throws LinphoneCoreException
385 public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
388 * Accept an incoming call.
390 * Basically the application is notified of incoming calls within the
391 * {@link LinphoneCoreListener#callState} listener method.
392 * The application can later respond positively to the call using
394 * @throws LinphoneCoreException
396 public void acceptCallWithParams(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
399 * Accept call modifications initiated by other end.
401 * Basically the application is notified of incoming calls within the
402 * {@link LinphoneCoreListener#callState} listener method.
403 * The application can later respond positively to the call using
405 * @throws LinphoneCoreException
407 public void acceptCallUpdate(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
411 * Prevent LinphoneCore from performing an automatic answer
413 * Basically the application is notified of incoming calls within the
414 * {@link LinphoneCoreListener#callState} listener method.
415 * The application can later respond positively to the call using
417 * @throws LinphoneCoreException
419 public void deferCallUpdate(LinphoneCall aCall) throws LinphoneCoreException;
422 * @return a list of LinphoneCallLog
424 public LinphoneCallLog[] getCallLogs();
427 * This method is called by the application to notify the Linphone core library when network is reachable.
428 * Calling this method with true trigger Linphone to initiate a registration process for all proxy
429 * configuration with parameter register set to enable.
430 * This method disable the automatic registration mode. It means you must call this method after each network state changes
431 * @param network state
434 public void setNetworkReachable(boolean isReachable);
437 * @return if false, there is no network connection.
439 public boolean isNetworkReachable();
441 * destroy linphone core and free all underlying resources
443 public void destroy();
445 * Allow to control play level before entering sound card:
448 public void setPlaybackGain(float gain);
450 * get play level before entering sound card:
451 * @return level in db
453 public float getPlaybackGain();
456 * @param level [0..100]
458 public void setPlayLevel(int level);
460 * get playback level [0..100];
461 * -1 if not cannot be determined
464 public int getPlayLevel();
466 * Mutes or unmutes the local microphone.
469 void muteMic(boolean isMuted);
472 * @return true is mic is muted
474 boolean isMicMuted();
477 * Initiate a dtmf signal if in call
480 void sendDtmf(char number);
482 * Initiate a dtmf signal to the speaker if not in call.
483 * Sending of the DTMF is done in another function.
485 * @param duration in ms , -1 for unlimited
487 void playDtmf(char number,int duration);
494 * remove all call logs
496 void clearCallLogs();
498 * get payload type from mime type, clock rate, and number of channels.-
500 * return null if not found
502 PayloadType findPayloadType(String mime, int clockRate, int channels);
504 * get payload type from mime type and clock rate..
506 * return null if not found
508 PayloadType findPayloadType(String mime, int clockRate);
510 * not implemented yet
513 * @throws LinphoneCoreException
515 void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
517 * Enables or disable echo cancellation.
520 void enableEchoCancellation(boolean enable);
523 * @return true if echo cancellation is enabled.
525 boolean isEchoCancellationEnabled();
527 * Get echo limiter status (another method of doing echo suppressionn, more brute force)
528 * @return true if echo limiter is enabled
530 boolean isEchoLimiterEnabled();
532 * @param transports used for signaling (TCP, UDP and TLS)
534 void setSignalingTransportPorts(Transports transports);
536 * @return transports used for signaling (TCP, UDP, TLS)
538 Transports getSignalingTransportPorts();
543 void enableSpeaker(boolean value);
548 boolean isSpeakerEnabled();
550 * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
551 * @param lf LinphoenFriend to add
552 * @throws LinphoneCoreException
554 void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
557 * Set my presence status
558 * @param minute_away how long in away
559 * @param status sip uri used to redirect call in state LinphoneStatusMoved
561 void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
563 * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
564 * @param to destination address for messages
566 * @return {@link LinphoneChatRoom} where messaging can take place.
568 LinphoneChatRoom createChatRoom(String to);
570 void setVideoWindow(Object w);
571 void setPreviewWindow(Object w);
572 void setDeviceRotation(int rotation);
574 void setVideoDevice(int id);
575 int getVideoDevice();
578 * Enables video globally.
581 * This function does not have any effect during calls. It just indicates #LinphoneCore to
582 * initiate future calls with video or not. The two boolean parameters indicate in which
583 * direction video is enabled. Setting both to false disables video entirely.
585 * @param vcap_enabled indicates whether video capture is enabled
586 * @param display_enabled indicates whether video display should be shown
589 void enableVideo(boolean vcap_enabled, boolean display_enabled);
591 * Returns TRUE if video is enabled, FALSE otherwise.
594 boolean isVideoEnabled();
597 * Specify a STUN server to help firewall traversal.
598 * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
600 void setStunServer(String stun_server);
602 * @return stun server address if previously set.
604 String getStunServer();
607 * Sets policy regarding workarounding NATs
608 * @param pol one of the FirewallPolicy members.
610 void setFirewallPolicy(FirewallPolicy pol);
612 * @return previously set firewall policy.
614 FirewallPolicy getFirewallPolicy();
616 LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
618 int updateCall(LinphoneCall call, LinphoneCallParams params);
620 LinphoneCallParams createDefaultCallParameters();
623 * Sets the path to a wav file used for ringing.
625 * @param path The file must be a wav 16bit linear. Local ring is disabled if null
627 void setRing(String path);
629 * gets the path to a wav file used for ringing.
631 * @param null if not set
636 * Sets file or folder containing trusted root CAs
638 * @param path path to file with multiple PEM certif or to folder with multiple PEM files
640 void setRootCA(String path);
642 void setUploadBandwidth(int bw);
644 void setDownloadBandwidth(int bw);
647 * Sets audio packetization interval suggested for remote end.
648 * @param ptime packetization interval in milliseconds
650 void setDownloadPtime(int ptime);
653 * Sets audio packetization interval sent to remote end.
654 * @param ptime packetization interval in milliseconds
656 void setUploadPtime(int ptime);
658 void setPreferredVideoSize(VideoSize vSize);
660 VideoSize getPreferredVideoSize();
663 * Returns the currently supported audio codecs, as PayloadType elements
666 PayloadType[] getAudioCodecs();
668 * Returns the currently supported video codecs, as PayloadType elements
671 PayloadType[] getVideoCodecs();
673 * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
675 void enableKeepAlive(boolean enable);
677 * get keep elive mode
678 * @return true if enable
680 boolean isKeepAliveEnabled();
682 * Start an echo calibration of the sound devices, in order to find adequate settings for the echo canceler automatically.
683 * status is notified to {@link LinphoneCoreListener#ecCalibrationStatus(EcCalibratorStatus, int, Object)}
685 * @throws LinphoneCoreException if operation is still in progress;
687 void startEchoCalibration(Object data) throws LinphoneCoreException;
689 void enableIpv6(boolean enable);
694 void adjustSoftwareVolume(int i);
696 boolean pauseCall(LinphoneCall call);
697 boolean resumeCall(LinphoneCall call);
698 boolean pauseAllCalls();
700 void setZrtpSecretsCache(String file);
701 void enableEchoLimiter(boolean val);
703 boolean isInConference();
704 boolean enterConference();
705 void leaveConference();
707 void addToConference(LinphoneCall call);
708 void addAllToConference();
709 void removeFromConference(LinphoneCall call);
711 void terminateConference();
712 int getConferenceSize();
714 void terminateAllCalls();
715 LinphoneCall[] getCalls();
719 void transferCall(LinphoneCall call, String referTo);
720 void transferCallToAnother(LinphoneCall callToTransfer, LinphoneCall destination);
722 LinphoneCall findCallFromUri(String uri);
725 void setMaxCalls(int max);
726 boolean isMyself(String uri);
729 * Use this method to check the calls state and forbid proposing actions
730 * which could result in an active call.
731 * Eg: don't start a new call if one is in outgoing ringing.
732 * Eg: don't merge to conference either as it could result
733 * in two active calls (conference and accepted call).
736 boolean soundResourcesLocked();
738 * Returns whether given media encryption is supported by liblinphone.
740 boolean mediaEncryptionSupported(MediaEncryption menc);
742 * set media encryption (rtp) to use
743 * @params menc: MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
745 void setMediaEncryption(MediaEncryption menc);
747 * return selected media encryption
748 * @return MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
750 MediaEncryption getMediaEncryption();
752 * Set media encryption required for outgoing calls
754 void setMediaEncryptionMandatory(boolean yesno);
756 * @return if media encryption is required for outgoing calls
758 boolean isMediaEncryptionMandatory();
761 * @param path path to music file played to remote side when on hold.
763 void setPlayFile(String path);
764 void tunnelEnable(boolean enable);
765 void tunnelAutoDetect();
766 void tunnelCleanServers();
767 void tunnelSetHttpProxy(String proxy_host, int port, String username, String password);
769 * @param host tunnel server ip address
770 * @param port tunnel server tls port, recommended value is 443
771 * @param udpMirrorPort remote port on the tunnel server side used to test udp reachability
772 * @param roundTripDelay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms
774 void tunnelAddServerAndMirror(String host, int port, int udpMirrorPort, int roundTripDelay);
776 boolean isTunnelAvailable();
778 LinphoneProxyConfig[] getProxyConfigList();
780 void setVideoPolicy(boolean autoInitiate, boolean autoAccept);
782 void setUserAgent(String name, String version);
784 void setCpuCount(int count);
789 public void removeCallLog(LinphoneCallLog log);
792 * @return count of missed calls
794 public int getMissedCallsCount();
797 * Set missed calls count to zero
799 public void resetMissedCallsCount();
801 * re-initiates registration if network is up.
803 public void refreshRegisters();
806 * return the version code of linphone core
808 public String getVersion();
811 * remove a linphone friend from linphone core and linphonerc
813 void removeFriend(LinphoneFriend lf);
816 * return a linphone friend (if exists) that matches the sip address
818 LinphoneFriend findFriendByAddress(String sipUri);
821 * Sets the UDP port used for audio streaming.
823 void setAudioPort(int port);
826 * Sets the UDP port range from which to randomly select the port used for audio streaming.
828 void setAudioPortRange(int minPort, int maxPort);
831 * Sets the UDP port used for video streaming.
833 void setVideoPort(int port);
836 * Sets the UDP port range from which to randomly select the port used for video streaming.
838 void setVideoPortRange(int minPort, int maxPort);
841 * Set the incoming call timeout in seconds.
842 * If an incoming call isn't answered for this timeout period, it is
843 * automatically declined.
845 void setIncomingTimeout(int timeout);
848 * Set the call timeout in seconds.
849 * Once this time is elapsed (ringing included), the call is automatically hung up.
851 void setInCallTimeout(int timeout);
853 void setUploadBandwidth(int bandwidth);
855 void setDownloadBandwidth(int bandwidth);
857 void setMicrophoneGain(float gain);