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<GlobalState> values = new Vector<GlobalState>();
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<RegistrationState> values = new Vector<RegistrationState>();
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<FirewallPolicy> values = new Vector<FirewallPolicy>();
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");
147 static public FirewallPolicy UseIce = new FirewallPolicy(4,"UseUpnp");
149 private final int mValue;
150 private final String mStringValue;
153 private FirewallPolicy(int value,String stringValue) {
155 values.addElement(this);
156 mStringValue=stringValue;
158 public static FirewallPolicy fromInt(int value) {
160 for (int i=0; i<values.size();i++) {
161 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
162 if (state.mValue == value) return state;
164 throw new RuntimeException("state not found ["+value+"]");
166 public String toString() {
175 * Signaling transports ports.
177 static public class Transports {
182 public Transports() {};
183 public Transports(Transports t) {
188 public String toString() {
189 return "udp["+udp+"] tcp["+tcp+"] tls["+tls+"]";
193 * Media (RTP) encryption enum-like.
196 static public final class MediaEncryption {
198 static private Vector<MediaEncryption> values = new Vector<MediaEncryption>();
202 static public final MediaEncryption None = new MediaEncryption(0,"None");
206 static public final MediaEncryption SRTP = new MediaEncryption(1,"SRTP");
210 static public final MediaEncryption ZRTP = new MediaEncryption(2,"ZRTP");
211 protected final int mValue;
212 private final String mStringValue;
215 private MediaEncryption(int value,String stringValue) {
217 values.addElement(this);
218 mStringValue=stringValue;
220 public static MediaEncryption fromInt(int value) {
222 for (int i=0; i<values.size();i++) {
223 MediaEncryption menc = (MediaEncryption) values.elementAt(i);
224 if (menc.mValue == value) return menc;
226 throw new RuntimeException("MediaEncryption not found ["+value+"]");
228 public String toString() {
233 * EC Calibrator Status
235 static public class EcCalibratorStatus {
237 static private Vector<EcCalibratorStatus> values = new Vector<EcCalibratorStatus>();
238 /* Do not change the values of these constants or the strings associated with them to prevent breaking
239 the collection of echo canceller calibration results during the wizard! */
240 public static final int IN_PROGRESS_STATUS=0;
241 public static final int DONE_STATUS=1;
242 public static final int FAILED_STATUS=2;
243 public static final int DONE_NO_ECHO_STATUS=3;
245 * Calibration in progress
247 static public EcCalibratorStatus InProgress = new EcCalibratorStatus(IN_PROGRESS_STATUS,"InProgress");
249 * Calibration done that produced an echo delay measure
251 static public EcCalibratorStatus Done = new EcCalibratorStatus(DONE_STATUS,"Done");
255 static public EcCalibratorStatus Failed = new EcCalibratorStatus(FAILED_STATUS,"Failed");
257 * Calibration done with no echo detected
259 static public EcCalibratorStatus DoneNoEcho = new EcCalibratorStatus(DONE_NO_ECHO_STATUS, "DoneNoEcho");
261 private final int mValue;
262 private final String mStringValue;
265 private EcCalibratorStatus(int value,String stringValue) {
267 values.addElement(this);
268 mStringValue=stringValue;
270 public static EcCalibratorStatus fromInt(int value) {
272 for (int i=0; i<values.size();i++) {
273 EcCalibratorStatus status = (EcCalibratorStatus) values.elementAt(i);
274 if (status.mValue == value) return status;
276 throw new RuntimeException("status not found ["+value+"]");
278 public String toString() {
286 static public class UpnpState {
287 static private Vector<UpnpState> values = new Vector<UpnpState>();
291 static public UpnpState Idle = new UpnpState(0, "Idle");
295 static public UpnpState Pending = new UpnpState(1, "Pending");
299 static public UpnpState Adding = new UpnpState(2, "Adding");
303 static public UpnpState Removing = new UpnpState(3, "Removing");
307 static public UpnpState NotAvailable = new UpnpState(4, "Not available");
311 static public UpnpState Ok = new UpnpState(5, "Ok");
315 static public UpnpState Ko = new UpnpState(6, "Ko");
316 protected final int mValue;
317 private final String mStringValue;
319 private UpnpState(int value, String stringValue) {
321 values.addElement(this);
322 mStringValue = stringValue;
324 public static UpnpState fromInt(int value) {
325 for (int i = 0; i < values.size(); i++) {
326 UpnpState mstate = (UpnpState) values.elementAt(i);
327 if (mstate.mValue == value) return mstate;
329 throw new RuntimeException("UpnpState not found [" + value + "]");
331 public String toString() {
337 * Set the context of creation of the LinphoneCore.
339 public void setContext(Object context);
342 * clear all added proxy configs
344 public void clearProxyConfigs();
346 * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
348 * @throws LinphoneCoreException
350 public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
352 * Sets the default proxy.
354 * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
355 * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
358 public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
361 * get he default proxy configuration, that is the one used to determine the current identity.
362 * @return null if no default proxy config
364 public LinphoneProxyConfig getDefaultProxyConfig() ;
367 * clear all the added auth info
369 void clearAuthInfos();
371 * Adds authentication information to the LinphoneCore.
372 * <br>This information will be used during all SIP transacations that require authentication.
375 void addAuthInfo(LinphoneAuthInfo info);
378 * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
381 * @throws If no LinphoneAddress can be built from destination
383 public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
386 * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
389 public LinphoneCall invite(String destination)throws LinphoneCoreException;
391 * Initiates an outgoing call given a destination LinphoneAddress
392 *<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.
393 * @param to the destination of the call (sip address).
394 * @return LinphoneCall
395 * @throws LinphoneCoreException
397 public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
400 * @param aCall to be terminated
402 public void terminateCall(LinphoneCall aCall);
404 * Declines an incoming call, providing a reason for declining it.
406 public void declineCall(LinphoneCall aCall, Reason reason);
408 * Returns The LinphoneCall the current call if one is in call
411 public LinphoneCall getCurrentCall();
414 * get current call remote address in case of in/out call
415 * @return null if no call engaged yet
417 public LinphoneAddress getRemoteAddress();
420 * @return TRUE if there is a call running or pending.
422 public boolean isIncall();
425 * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
427 public boolean isInComingInvitePending();
429 * Main loop function. It is crucial that your application call it periodically.
431 * #iterate() performs various backgrounds tasks:
432 * <li>receiving of SIP messages
433 * <li> handles timers and timeout
434 * <li> performs registration to proxies
435 * <li> authentication retries The application MUST call this function from periodically, in its main loop.
436 * <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.
439 public void iterate();
441 * Accept an incoming call.
443 * Basically the application is notified of incoming calls within the
444 * {@link LinphoneCoreListener#callState} listener method.
445 * The application can later respond positively to the call using
447 * @throws LinphoneCoreException
449 public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
452 * Accept an incoming call.
454 * Basically the application is notified of incoming calls within the
455 * {@link LinphoneCoreListener#callState} listener method.
456 * The application can later respond positively to the call using
458 * @throws LinphoneCoreException
460 public void acceptCallWithParams(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
463 * Accept call modifications initiated by other end.
465 * Basically the application is notified of incoming calls within the
466 * {@link LinphoneCoreListener#callState} listener method.
467 * The application can later respond positively to the call using
469 * @throws LinphoneCoreException
471 public void acceptCallUpdate(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
475 * Prevent LinphoneCore from performing an automatic answer
477 * Basically the application is notified of incoming calls within the
478 * {@link LinphoneCoreListener#callState} listener method.
479 * The application can later respond positively to the call using
481 * @throws LinphoneCoreException
483 public void deferCallUpdate(LinphoneCall aCall) throws LinphoneCoreException;
485 public void startRinging();
488 * @return a list of LinphoneCallLog
490 public LinphoneCallLog[] getCallLogs();
493 * This method is called by the application to notify the Linphone core library when network is reachable.
494 * Calling this method with true trigger Linphone to initiate a registration process for all proxy
495 * configuration with parameter register set to enable.
496 * This method disable the automatic registration mode. It means you must call this method after each network state changes
497 * @param network state
500 public void setNetworkReachable(boolean isReachable);
503 * @return if false, there is no network connection.
505 public boolean isNetworkReachable();
507 * destroy linphone core and free all underlying resources
509 public void destroy();
511 * Allow to control play level before entering sound card:
514 public void setPlaybackGain(float gain);
516 * get play level before entering sound card:
517 * @return level in db
519 public float getPlaybackGain();
522 * @param level [0..100]
524 public void setPlayLevel(int level);
526 * get playback level [0..100];
527 * -1 if not cannot be determined
530 public int getPlayLevel();
532 * Mutes or unmutes the local microphone.
535 void muteMic(boolean isMuted);
538 * @return true is mic is muted
540 boolean isMicMuted();
543 * Initiate a dtmf signal if in call
546 void sendDtmf(char number);
548 * Initiate a dtmf signal to the speaker if not in call.
549 * Sending of the DTMF is done in another function.
551 * @param duration in ms , -1 for unlimited
553 void playDtmf(char number,int duration);
560 * remove all call logs
562 void clearCallLogs();
564 * get payload type from mime type, clock rate, and number of channels.-
566 * return null if not found
568 PayloadType findPayloadType(String mime, int clockRate, int channels);
570 * get payload type from mime type and clock rate..
572 * return null if not found
574 PayloadType findPayloadType(String mime, int clockRate);
576 * not implemented yet
579 * @throws LinphoneCoreException
581 void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
583 * Enables or disable echo cancellation.
586 void enableEchoCancellation(boolean enable);
589 * @return true if echo cancellation is enabled.
591 boolean isEchoCancellationEnabled();
593 * Get echo limiter status (another method of doing echo suppression, more brute force)
594 * @return true if echo limiter is enabled
596 boolean isEchoLimiterEnabled();
598 * @param transports used for signaling (TCP, UDP and TLS)
600 void setSignalingTransportPorts(Transports transports);
602 * @return transports used for signaling (TCP, UDP, TLS)
604 Transports getSignalingTransportPorts();
606 * Activates or deactivates the speaker.
609 void enableSpeaker(boolean value);
611 * Tells whether the speaker is activated.
612 * @return true if speaker enabled, false otherwise
614 boolean isSpeakerEnabled();
616 * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
617 * @param lf LinphoenFriend to add
618 * @throws LinphoneCoreException
620 void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
623 * Set my presence status
624 * @param minute_away how long in away
625 * @param status sip uri used to redirect call in state LinphoneStatusMoved
627 void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
629 * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
630 * @param to destination address for messages
632 * @return {@link LinphoneChatRoom} where messaging can take place.
634 LinphoneChatRoom createChatRoom(String to);
636 void setVideoWindow(Object w);
637 void setPreviewWindow(Object w);
638 void setDeviceRotation(int rotation);
640 void setVideoDevice(int id);
641 int getVideoDevice();
644 * Enables video globally.
647 * This function does not have any effect during calls. It just indicates #LinphoneCore to
648 * initiate future calls with video or not. The two boolean parameters indicate in which
649 * direction video is enabled. Setting both to false disables video entirely.
651 * @param vcap_enabled indicates whether video capture is enabled
652 * @param display_enabled indicates whether video display should be shown
655 void enableVideo(boolean vcap_enabled, boolean display_enabled);
657 * Returns TRUE if video is enabled, FALSE otherwise.
660 boolean isVideoEnabled();
663 * Specify a STUN server to help firewall traversal.
664 * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
666 void setStunServer(String stun_server);
668 * @return stun server address if previously set.
670 String getStunServer();
673 * Sets policy regarding workarounding NATs
674 * @param pol one of the FirewallPolicy members.
676 void setFirewallPolicy(FirewallPolicy pol);
678 * @return previously set firewall policy.
680 FirewallPolicy getFirewallPolicy();
682 LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
684 int updateCall(LinphoneCall call, LinphoneCallParams params);
686 LinphoneCallParams createDefaultCallParameters();
689 * Sets the path to a wav file used for ringing.
691 * @param path The file must be a wav 16bit linear. Local ring is disabled if null
693 void setRing(String path);
695 * gets the path to a wav file used for ringing.
697 * @param null if not set
702 * Sets file or folder containing trusted root CAs
704 * @param path path to file with multiple PEM certif or to folder with multiple PEM files
706 void setRootCA(String path);
708 void setUploadBandwidth(int bw);
710 void setDownloadBandwidth(int bw);
713 * Sets audio packetization interval suggested for remote end.
714 * @param ptime packetization interval in milliseconds
716 void setDownloadPtime(int ptime);
719 * Sets audio packetization interval sent to remote end.
720 * @param ptime packetization interval in milliseconds
722 void setUploadPtime(int ptime);
724 void setPreferredVideoSize(VideoSize vSize);
726 VideoSize getPreferredVideoSize();
729 * Returns the currently supported audio codecs, as PayloadType elements
732 PayloadType[] getAudioCodecs();
734 * Returns the currently supported video codecs, as PayloadType elements
737 PayloadType[] getVideoCodecs();
739 * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
741 void enableKeepAlive(boolean enable);
743 * get keep elive mode
744 * @return true if enable
746 boolean isKeepAliveEnabled();
748 * Start an echo calibration of the sound devices, in order to find adequate settings for the echo canceler automatically.
749 * status is notified to {@link LinphoneCoreListener#ecCalibrationStatus(EcCalibratorStatus, int, Object)}
751 * @throws LinphoneCoreException if operation is still in progress;
753 void startEchoCalibration(Object data) throws LinphoneCoreException;
756 * Returns true if echo calibration is recommended.
757 * If the device has a builtin echo canceller or calibration value is already known, it will return false.
759 boolean needsEchoCalibration();
761 void enableIpv6(boolean enable);
766 void adjustSoftwareVolume(int i);
771 boolean pauseCall(LinphoneCall call);
775 boolean resumeCall(LinphoneCall call);
776 boolean pauseAllCalls();
778 void setZrtpSecretsCache(String file);
779 void enableEchoLimiter(boolean val);
782 * Indicates whether the local user is part of the conference.
784 boolean isInConference();
786 * Connect the local user to the conference.
788 boolean enterConference();
790 * Disconnect the local user from the conference.
792 void leaveConference();
795 * Add an established call to the conference. The LinphoneCore is able to manage one client based conference.
797 void addToConference(LinphoneCall call);
799 * Remove an established call from the conference.
801 void removeFromConference(LinphoneCall call);
802 void addAllToConference();
805 * Terminate the conference, all users are disconnected.
807 void terminateConference();
808 int getConferenceSize();
811 * Request recording of the conference into a supplied file path.
814 void startConferenceRecording(String path);
817 * Stop recording of the conference.
819 void stopConferenceRecording();
821 void terminateAllCalls();
825 LinphoneCall[] getCalls();
829 void transferCall(LinphoneCall call, String referTo);
830 void transferCallToAnother(LinphoneCall callToTransfer, LinphoneCall destination);
832 LinphoneCall findCallFromUri(String uri);
835 void setMaxCalls(int max);
836 boolean isMyself(String uri);
839 * Use this method to check the calls state and forbid proposing actions
840 * which could result in an active call.
841 * Eg: don't start a new call if one is in outgoing ringing.
842 * Eg: don't merge to conference either as it could result
843 * in two active calls (conference and accepted call).
846 boolean soundResourcesLocked();
848 * Returns whether given media encryption is supported by liblinphone.
850 boolean mediaEncryptionSupported(MediaEncryption menc);
852 * set media encryption (rtp) to use
853 * @params menc: MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
855 void setMediaEncryption(MediaEncryption menc);
857 * return selected media encryption
858 * @return MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
860 MediaEncryption getMediaEncryption();
862 * Set media encryption required for outgoing calls
864 void setMediaEncryptionMandatory(boolean yesno);
866 * @return if media encryption is required for outgoing calls
868 boolean isMediaEncryptionMandatory();
871 * @param path path to music file played to remote side when on hold.
873 void setPlayFile(String path);
874 void tunnelEnable(boolean enable);
875 void tunnelAutoDetect();
876 void tunnelCleanServers();
877 void tunnelSetHttpProxy(String proxy_host, int port, String username, String password);
879 * @param host tunnel server ip address
880 * @param port tunnel server tls port, recommended value is 443
881 * @param udpMirrorPort remote port on the tunnel server side used to test udp reachability
882 * @param roundTripDelay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms
884 void tunnelAddServerAndMirror(String host, int port, int udpMirrorPort, int roundTripDelay);
886 boolean isTunnelAvailable();
888 LinphoneProxyConfig[] getProxyConfigList();
890 void setVideoPolicy(boolean autoInitiate, boolean autoAccept);
892 void setStaticPicture(String path);
894 void setUserAgent(String name, String version);
896 void setCpuCount(int count);
901 public void removeCallLog(LinphoneCallLog log);
904 * @return count of missed calls
906 public int getMissedCallsCount();
909 * Set missed calls count to zero
911 public void resetMissedCallsCount();
913 * re-initiates registration if network is up.
915 public void refreshRegisters();
918 * return the version code of linphone core
920 public String getVersion();
923 * remove a linphone friend from linphone core and linphonerc
925 void removeFriend(LinphoneFriend lf);
928 * return a linphone friend (if exists) that matches the sip address
930 LinphoneFriend findFriendByAddress(String sipUri);
933 * Sets the UDP port used for audio streaming.
935 void setAudioPort(int port);
938 * Sets the UDP port range from which to randomly select the port used for audio streaming.
940 void setAudioPortRange(int minPort, int maxPort);
943 * Sets the UDP port used for video streaming.
945 void setVideoPort(int port);
948 * Sets the UDP port range from which to randomly select the port used for video streaming.
950 void setVideoPortRange(int minPort, int maxPort);
953 * Set the incoming call timeout in seconds.
954 * If an incoming call isn't answered for this timeout period, it is
955 * automatically declined.
957 void setIncomingTimeout(int timeout);
960 * Set the call timeout in seconds.
961 * Once this time is elapsed (ringing included), the call is automatically hung up.
963 void setInCallTimeout(int timeout);
965 void setMicrophoneGain(float gain);
968 * Set username and display name to use if no LinphoneProxyConfig configured
970 void setPrimaryContact(String displayName, String username);
973 * Enable/Disable the use of SIP INFO for DTMFs
975 void setUseSipInfoForDtmfs(boolean use);
978 * Enable/Disable the use of inband DTMFs
980 void setUseRfc2833ForDtmfs(boolean use);
983 * @return returns LpConfig object to read/write to the config file: usefull if you wish to extend
984 * the config file with your own sections
986 LpConfig getConfig();
990 * Return the availability of uPnP.
992 * @return true if uPnP is available otherwise return false.
994 public boolean upnpAvailable();
997 * Return the internal state of uPnP.
999 * @return an UpnpState.
1001 public UpnpState getUpnpState();
1004 * Return the external ip address of router.
1005 * In some cases the uPnP can have an external ip address but not a usable uPnP
1006 * (state different of Ok).
1008 * @return a null terminated string containing the external ip address. If the
1009 * the external ip address is not available return null.
1011 public String getUpnpExternalIpaddress();