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;
23 import org.linphone.core.LinphoneCallParams;
26 * Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.
30 public interface LinphoneCore {
32 * linphone core states
34 static public class GlobalState {
36 static private Vector values = new Vector();
40 static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");
44 static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
48 static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
52 static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
54 private final int mValue;
55 private final String mStringValue;
58 private GlobalState(int value,String stringValue) {
60 values.addElement(this);
61 mStringValue=stringValue;
63 public static GlobalState fromInt(int value) {
65 for (int i=0; i<values.size();i++) {
66 GlobalState state = (GlobalState) values.elementAt(i);
67 if (state.mValue == value) return state;
69 throw new RuntimeException("state not found ["+value+"]");
71 public String toString() {
76 * Describes proxy registration states.
79 static public class RegistrationState {
81 private static Vector values = new Vector();
85 public static RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");
89 public static RegistrationState RegistrationProgress = new RegistrationState(1,"RegistrationProgress");
93 public static RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
97 public static RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
101 public static RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
102 private final int mValue;
103 private final String mStringValue;
106 private RegistrationState(int value,String stringValue) {
108 values.addElement(this);
109 mStringValue=stringValue;
111 public static RegistrationState fromInt(int value) {
113 for (int i=0; i<values.size();i++) {
114 RegistrationState state = (RegistrationState) values.elementAt(i);
115 if (state.mValue == value) return state;
117 throw new RuntimeException("state not found ["+value+"]");
119 public String toString() {
124 * Describes firewall policy.
127 static public class FirewallPolicy {
129 static private Vector values = new Vector();
131 * No firewall is assumed.
133 static public FirewallPolicy NoFirewall = new FirewallPolicy(0,"NoFirewall");
135 * Use NAT address (discouraged)
137 static public FirewallPolicy UseNatAddress = new FirewallPolicy(1,"UseNatAddress");
139 * Use stun server to discover RTP addresses and ports.
141 static public FirewallPolicy UseStun = new FirewallPolicy(2,"UseStun");
143 private final int mValue;
144 private final String mStringValue;
147 private FirewallPolicy(int value,String stringValue) {
149 values.addElement(this);
150 mStringValue=stringValue;
152 public static FirewallPolicy fromInt(int value) {
154 for (int i=0; i<values.size();i++) {
155 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
156 if (state.mValue == value) return state;
158 throw new RuntimeException("state not found ["+value+"]");
160 public String toString() {
169 * Signaling transports ports.
171 static public class Transports {
176 public Transports() {};
177 public Transports(Transports t) {
184 * Media (RTP) encryption enum-like.
187 static public class MediaEncryption {
189 static private Vector values = new Vector();
193 static public MediaEncryption None = new MediaEncryption(0,"None");
197 static public MediaEncryption SRTP = new MediaEncryption(1,"SRTP");
201 static public MediaEncryption ZRTP = new MediaEncryption(2,"ZRTP");
202 protected final int mValue;
203 private final String mStringValue;
206 private MediaEncryption(int value,String stringValue) {
208 values.addElement(this);
209 mStringValue=stringValue;
211 public static MediaEncryption fromInt(int value) {
213 for (int i=0; i<values.size();i++) {
214 MediaEncryption menc = (MediaEncryption) values.elementAt(i);
215 if (menc.mValue == value) return menc;
217 throw new RuntimeException("MediaEncryption not found ["+value+"]");
219 public String toString() {
224 * EC Calibrator Status
226 static public class EcCalibratorStatus {
228 static private Vector values = new Vector();
229 public static final int IN_PROGRESS_STATUS=0;
230 public static final int DONE_STATUS=1;
231 public static final int FAILED_STATUS=2;
233 * Calibration in progress
235 static public EcCalibratorStatus InProgress = new EcCalibratorStatus(IN_PROGRESS_STATUS,"InProgress");
239 static public EcCalibratorStatus Done = new EcCalibratorStatus(DONE_STATUS,"Done");
241 * Calibration in progress
243 static public EcCalibratorStatus Failed = new EcCalibratorStatus(FAILED_STATUS,"Failed");
245 private final int mValue;
246 private final String mStringValue;
249 private EcCalibratorStatus(int value,String stringValue) {
251 values.addElement(this);
252 mStringValue=stringValue;
254 public static EcCalibratorStatus fromInt(int value) {
256 for (int i=0; i<values.size();i++) {
257 EcCalibratorStatus status = (EcCalibratorStatus) values.elementAt(i);
258 if (status.mValue == value) return status;
260 throw new RuntimeException("status not found ["+value+"]");
262 public String toString() {
270 * clear all added proxy configs
272 public void clearProxyConfigs();
274 * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
276 * @throws LinphoneCoreException
278 public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
280 * Sets the default proxy.
282 * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}.
283 * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
286 public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
289 * get he default proxy configuration, that is the one used to determine the current identity.
290 * @return null if no default proxy config
292 public LinphoneProxyConfig getDefaultProxyConfig() ;
295 * clear all the added auth info
297 void clearAuthInfos();
299 * Adds authentication information to the LinphoneCore.
300 * <br>This information will be used during all SIP transacations that require authentication.
303 void addAuthInfo(LinphoneAuthInfo info);
306 * Build an address according to the current proxy config. In case destination is not a sip address, the default proxy domain is automatically appended
309 * @throws If no LinphoneAddress can be built from destination
311 public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
314 * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
317 public LinphoneCall invite(String destination)throws LinphoneCoreException;
319 * Initiates an outgoing call given a destination LinphoneAddress
320 *<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.
321 * @param to the destination of the call (sip address).
322 * @return LinphoneCall
323 * @throws LinphoneCoreException
325 public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
328 * @param aCall to be terminated
330 public void terminateCall(LinphoneCall aCall);
332 * Returns The LinphoneCall the current call if one is in call
335 public LinphoneCall getCurrentCall();
338 * get current call remote address in case of in/out call
339 * @return null if no call engaged yet
341 public LinphoneAddress getRemoteAddress();
344 * @return TRUE if there is a call running or pending.
346 public boolean isIncall();
349 * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
351 public boolean isInComingInvitePending();
353 * Main loop function. It is crucial that your application call it periodically.
355 * #iterate() performs various backgrounds tasks:
356 * <li>receiving of SIP messages
357 * <li> handles timers and timeout
358 * <li> performs registration to proxies
359 * <li> authentication retries The application MUST call this function from periodically, in its main loop.
360 * <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.
363 public void iterate();
365 * Accept an incoming call.
367 * Basically the application is notified of incoming calls within the
368 * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
369 * The application can later respond positively to the call using
371 * @throws LinphoneCoreException
373 public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
376 * Accept an incoming call.
378 * Basically the application is notified of incoming calls within the
379 * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
380 * The application can later respond positively to the call using
382 * @throws LinphoneCoreException
384 public void acceptCallWithParams(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
387 * Accept call modifications initiated by other end.
389 * Basically the application is notified of incoming calls within the
390 * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
391 * The application can later respond positively to the call using
393 * @throws LinphoneCoreException
395 public void acceptCallUpdate(LinphoneCall aCall, LinphoneCallParams params) throws LinphoneCoreException;
399 * Prevent LinphoneCore from performing an automatic answer
401 * Basically the application is notified of incoming calls within the
402 * {@link LinphoneCoreListener#inviteReceived(LinphoneCore, String)} listener.
403 * The application can later respond positively to the call using
405 * @throws LinphoneCoreException
407 public void deferCallUpdate(LinphoneCall aCall) throws LinphoneCoreException;
410 * @return a list of LinphoneCallLog
412 public LinphoneCallLog[] getCallLogs();
415 * This method is called by the application to notify the Linphone core library when network is reachable.
416 * Calling this method with true trigger Linphone to initiate a registration process for all proxy
417 * configuration with parameter register set to enable.
418 * This method disable the automatic registration mode. It means you must call this method after each network state changes
419 * @param network state
422 public void setNetworkReachable(boolean isReachable);
425 * @return if false, there is no network connection.
427 public boolean isNetworkReachable();
429 * destroy linphone core and free all underlying resources
431 public void destroy();
433 * Allow to control play level before entering sound card:
436 public void setPlaybackGain(float gain);
438 * get play level before entering sound card:
439 * @return level in db
441 public float getPlaybackGain();
444 * @param level [0..100]
446 public void setPlayLevel(int level);
448 * get playback level [0..100];
449 * -1 if not cannot be determined
452 public int getPlayLevel();
454 * Mutes or unmutes the local microphone.
457 void muteMic(boolean isMuted);
460 * @return true is mic is muted
462 boolean isMicMuted();
465 * Initiate a dtmf signal if in call
468 void sendDtmf(char number);
470 * Initiate a dtmf signal to the speaker if not in call.
471 * Sending of the DTMF is done in another function.
473 * @param duration in ms , -1 for unlimited
475 void playDtmf(char number,int duration);
482 * remove all call logs
484 void clearCallLogs();
486 * get payload type from mime type an clock rate
488 * return null if not found
490 PayloadType findPayloadType(String mime,int clockRate);
492 * not implemented yet
495 * @throws LinphoneCoreException
497 void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
499 * Enables or disable echo cancellation.
502 void enableEchoCancellation(boolean enable);
505 * @return true if echo cancellation is enabled.
507 boolean isEchoCancellationEnabled();
509 * Get echo limiter status (another method of doing echo suppressionn, more brute force)
510 * @return true if echo limiter is enabled
512 boolean isEchoLimiterEnabled();
514 * @param transports used for signaling (TCP, UDP and TLS)
516 void setSignalingTransportPorts(Transports transports);
518 * @return transports used for signaling (TCP, UDP, TLS)
520 Transports getSignalingTransportPorts();
525 void enableSpeaker(boolean value);
530 boolean isSpeakerEnabled();
532 * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
533 * @param lf LinphoenFriend to add
534 * @throws LinphoneCoreException
536 void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
539 * Set my presence status
540 * @param minute_away how long in away
541 * @param status sip uri used to redirect call in state LinphoneStatusMoved
543 void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
545 * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
546 * @param to destination address for messages
548 * @return {@link LinphoneChatRoom} where messaging can take place.
550 LinphoneChatRoom createChatRoom(String to);
552 void setVideoWindow(Object w);
553 void setPreviewWindow(Object w);
554 void setDeviceRotation(int rotation);
556 void setVideoDevice(int id);
557 int getVideoDevice();
560 * Enables video globally.
563 * This function does not have any effect during calls. It just indicates #LinphoneCore to
564 * initiate future calls with video or not. The two boolean parameters indicate in which
565 * direction video is enabled. Setting both to false disables video entirely.
567 * @param vcap_enabled indicates whether video capture is enabled
568 * @param display_enabled indicates whether video display should be shown
571 void enableVideo(boolean vcap_enabled, boolean display_enabled);
573 * Returns TRUE if video is enabled, FALSE otherwise.
576 boolean isVideoEnabled();
579 * Specify a STUN server to help firewall traversal.
580 * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
582 void setStunServer(String stun_server);
584 * @return stun server address if previously set.
586 String getStunServer();
589 * Sets policy regarding workarounding NATs
590 * @param pol one of the FirewallPolicy members.
592 void setFirewallPolicy(FirewallPolicy pol);
594 * @return previously set firewall policy.
596 FirewallPolicy getFirewallPolicy();
598 LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
600 int updateCall(LinphoneCall call, LinphoneCallParams params);
602 LinphoneCallParams createDefaultCallParameters();
605 * Sets the path to a wav file used for ringing.
607 * @param path The file must be a wav 16bit linear. Local ring is disabled if null
609 void setRing(String path);
611 * gets the path to a wav file used for ringing.
613 * @param null if not set
618 * Sets file or folder containing trusted root CAs
620 * @param path path to file with multiple PEM certif or to folder with multiple PEM files
622 void setRootCA(String path);
624 void setUploadBandwidth(int bw);
626 void setDownloadBandwidth(int bw);
629 * Sets audio packetization interval suggested for remote end.
630 * @param ptime packetization interval in milliseconds
632 void setDownloadPtime(int ptime);
635 * Sets audio packetization interval sent to remote end.
636 * @param ptime packetization interval in milliseconds
638 void setUploadPtime(int ptime);
640 void setPreferredVideoSize(VideoSize vSize);
642 VideoSize getPreferredVideoSize();
645 * Returns the currently supported audio codecs, as PayloadType elements
648 PayloadType[] getAudioCodecs();
650 * Returns the currently supported video codecs, as PayloadType elements
653 PayloadType[] getVideoCodecs();
655 * enable signaling keep alive. small udp packet sent periodically to keep udp NAT association
657 void enableKeepAlive(boolean enable);
659 * get keep elive mode
660 * @return true if enable
662 boolean isKeepAliveEnabled();
664 * Start an echo calibration of the sound devices, in order to find adequate settings for the echo canceler automatically.
665 * status is notified to {@link LinphoneCoreListener#ecCalibrationStatus(EcCalibratorStatus, int, Object)}
667 * @throws LinphoneCoreException if operation is still in progress;
669 void startEchoCalibration(Object data) throws LinphoneCoreException;
671 void enableIpv6(boolean enable);
672 void adjustSoftwareVolume(int i);
674 boolean pauseCall(LinphoneCall call);
675 boolean resumeCall(LinphoneCall call);
676 boolean pauseAllCalls();
678 void setZrtpSecretsCache(String file);
679 void enableEchoLimiter(boolean val);
681 boolean isInConference();
682 boolean enterConference();
683 void leaveConference();
685 void addToConference(LinphoneCall call);
686 void addAllToConference();
687 void removeFromConference(LinphoneCall call);
689 void terminateConference();
690 int getConferenceSize();
692 void terminateAllCalls();
693 LinphoneCall[] getCalls();
697 void transferCall(LinphoneCall call, String referTo);
698 void transferCallToAnother(LinphoneCall callToTransfer, LinphoneCall destination);
700 LinphoneCall findCallFromUri(String uri);
703 void setMaxCalls(int max);
704 boolean isMyself(String uri);
707 * Use this method to check the calls state and forbid proposing actions
708 * which could result in an active call.
709 * Eg: don't start a new call if one is in outgoing ringing.
710 * Eg: don't merge to conference either as it could result
711 * in two active calls (conference and accepted call).
714 boolean soundResourcesLocked();
716 * Returns whether given media encryption is supported by liblinphone.
718 boolean mediaEncryptionSupported(MediaEncryption menc);
720 * set media encryption (rtp) to use
721 * @params menc: MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
723 void setMediaEncryption(MediaEncryption menc);
725 * return selected media encryption
726 * @return MediaEncryption.None, MediaEncryption.SRTP or MediaEncryption.ZRTP
728 MediaEncryption getMediaEncryption();
730 * Set media encryption required for outgoing calls
732 void setMediaEncryptionMandatory(boolean yesno);
734 * @return if media encryption is required for outgoing calls
736 boolean isMediaEncryptionMandatory();
739 * @param path path to music file played to remote side when on hold.
741 void setPlayFile(String path);
742 void tunnelEnable(boolean enable);
743 void tunnelAutoDetect();
744 void tunnelEnableLogs(boolean enable);
745 void tunnelCleanServers();
747 * @param host tunnel server ip address
748 * @param port tunnel server tls port, recommended value is 443
749 * @param udpMirrorPort remote port on the tunnel server side used to test udp reachability
750 * @param roundTripDelay udp packet round trip delay in ms considered as acceptable. recommended value is 1000 ms
752 void tunnelAddServerAndMirror(String host, int port, int udpMirrorPort, int roundTripDelay);
754 boolean isTunnelAvailable();
756 LinphoneProxyConfig[] getProxyConfigList();
758 void setVideoPolicy(boolean autoInitiate, boolean autoAccept);
760 void setUserAgent(String name, String version);
762 void setCpuCount(int count);