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;
22 import java.util.Vector;
25 * 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 {
33 static private Vector values = new Vector();
37 static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");
41 static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
45 static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
49 static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
51 private final int mValue;
52 private final String mStringValue;
54 private GlobalState(int value,String stringValue) {
56 values.addElement(this);
57 mStringValue=stringValue;
59 public static GlobalState fromInt(int value) {
61 for (int i=0; i<values.size();i++) {
62 GlobalState state = (GlobalState) values.elementAt(i);
63 if (state.mValue == value) return state;
65 throw new RuntimeException("state not found ["+value+"]");
67 public String toString() {
72 * Describes proxy registration states.
75 static public class RegistrationState {
76 static private Vector values = new Vector();
80 static public RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");
84 static public RegistrationState RegistrationProgress = new RegistrationState(1,"RegistrationProgress");
88 static public RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
92 static public RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
96 static public RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
97 private final int mValue;
98 private final String mStringValue;
100 private RegistrationState(int value,String stringValue) {
102 values.addElement(this);
103 mStringValue=stringValue;
105 public static RegistrationState fromInt(int value) {
107 for (int i=0; i<values.size();i++) {
108 RegistrationState state = (RegistrationState) values.elementAt(i);
109 if (state.mValue == value) return state;
111 throw new RuntimeException("state not found ["+value+"]");
113 public String toString() {
118 * Describes firewall policy.
121 static public class FirewallPolicy {
122 static private Vector values = new Vector();
124 * No firewall is assumed.
126 static public FirewallPolicy NoFirewall = new FirewallPolicy(0,"NoFirewall");
128 * Use NAT address (discouraged)
130 static public FirewallPolicy UseNatAddress = new FirewallPolicy(1,"UseNatAddress");
132 * Use stun server to discover RTP addresses and ports.
134 static public FirewallPolicy UseStun = new FirewallPolicy(2,"UseStun");
136 private final int mValue;
137 private final String mStringValue;
139 private FirewallPolicy(int value,String stringValue) {
141 values.addElement(this);
142 mStringValue=stringValue;
144 public static FirewallPolicy fromInt(int value) {
146 for (int i=0; i<values.size();i++) {
147 FirewallPolicy state = (FirewallPolicy) values.elementAt(i);
148 if (state.mValue == value) return state;
150 throw new RuntimeException("state not found ["+value+"]");
152 public String toString() {
160 * Signaling transports
163 static public class Transport {
167 public final static Transport udp =new Transport("udp");
171 public final static Transport tcp =new Transport("tcp");
172 private final String mStringValue;
174 private Transport(String stringValue) {
175 mStringValue=stringValue;
177 public String toString() {
182 * clear all added proxy configs
184 public void clearProxyConfigs();
186 * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
188 * @throws LinphoneCoreException
190 public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
192 * Sets the default proxy.
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.
198 public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
201 * get he default proxy configuration, that is the one used to determine the current identity.
202 * @return null if no default proxy config
204 public LinphoneProxyConfig getDefaultProxyConfig() ;
207 * clear all the added auth info
209 void clearAuthInfos();
211 * Adds authentication information to the LinphoneCore.
212 * <br>This information will be used during all SIP transacations that require authentication.
215 void addAuthInfo(LinphoneAuthInfo info);
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
221 * @throws If no LinphoneAddress can be built from destination
223 public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
226 * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
229 public LinphoneCall invite(String destination)throws LinphoneCoreException;
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
237 public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
240 * @param aCall to be terminated
242 public void terminateCall(LinphoneCall aCall);
244 * Returns The LinphoneCall the current call if one is in call
247 public LinphoneCall getCurrentCall();
250 * get current call remote address in case of in/out call
251 * @return null if no call engaged yet
253 public LinphoneAddress getRemoteAddress();
256 * @return TRUE if there is a call running or pending.
258 public boolean isIncall();
261 * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
263 public boolean isInComingInvitePending();
265 * Main loop function. It is crucial that your application call it periodically.
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.
275 public void iterate();
277 * Accept an incoming call.
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
283 * @throws LinphoneCoreException
285 public void acceptCall(LinphoneCall aCall) throws LinphoneCoreException;
289 * @return a list of LinphoneCallLog
291 public Vector getCallLogs();
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
301 public void setNetworkStateReachable(boolean isReachable);
304 * @return if false, there is no network connection.
306 public boolean setNetworkStateReachable();
308 * destroy linphone core and free all underlying resources
310 public void destroy();
312 * Allow to control play level before entering sound card:
315 public void setPlaybackGain(float gain);
317 * get play level before entering sound card:
318 * @return level in db
320 public float getPlaybackGain();
323 * @param level [0..100]
325 public void setPlayLevel(int level);
327 * get playback level [0..100];
328 * -1 if not cannot be determined
331 public int getPlayLevel();
333 * Mutes or unmutes the local microphone.
336 public void muteMic(boolean isMuted);
339 * @return true is mic is muted
341 public boolean isMicMuted();
344 * Initiate a dtmf signal if in call
347 public void sendDtmf(char number);
349 * Initiate a dtmf signal to the speqker if not in call
351 * @param duration in ms , -1 for unlimited
353 public void playDtmf(char number,int duration);
357 public void stopDtmf();
360 * remove all call logs
362 public void clearCallLogs();
364 * get payload type from mime type an clock rate
366 * return null if not found
368 public PayloadType findPayloadType(String mime,int clockRate);
370 * not implemented yet
373 * @throws LinphoneCoreException
375 public void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
377 * Enables or disable echo cancellation.
380 public void enableEchoCancellation(boolean enable);
383 * @return true if echo cancellation is enabled.
385 public boolean isEchoCancellationEnabled();
387 * not implemented yet
390 public void setSignalingTransport(Transport aTransport);
395 public void enableSpeaker(boolean value);
400 public boolean isSpeakerEnabled();
402 * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.
403 * @param lf LinphoenFriend to add
404 * @throws LinphoneCoreException
406 void addFriend(LinphoneFriend lf) throws LinphoneCoreException;
409 * Set my presence status
410 * @param minute_away how long in away
411 * @param status sip uri used to redirect call in state LinphoneStatusMoved
413 void setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status);
415 * Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org
416 * @param to destination address for messages
418 * @return {@link LinphoneChatRoom} where messaging can take place.
420 LinphoneChatRoom createChatRoom(String to);
422 public void setVideoWindow(Object w);
423 public void setPreviewWindow(Object w);
425 * Enables video globally.
428 * This function does not have any effect during calls. It just indicates #LinphoneCore to
429 * initiate future calls with video or not. The two boolean parameters indicate in which
430 * direction video is enabled. Setting both to false disables video entirely.
432 * @param vcap_enabled indicates whether video capture is enabled
433 * @param display_enabled indicates whether video display should be shown
436 void enableVideo(boolean vcap_enabled, boolean display_enabled);
438 * Returns TRUE if video is enabled, FALSE otherwise.
441 boolean isVideoEnabled();
444 * Specify a STUN server to help firewall traversal.
445 * @param stun_server Stun server address and port, such as stun.linphone.org or stun.linphone.org:3478
447 public void setStunServer(String stun_server);
449 * @return stun server address if previously set.
451 public String getStunServer();
454 * Sets policy regarding workarounding NATs
455 * @param pol one of the FirewallPolicy members.
457 public void setFirewallPolicy(FirewallPolicy pol);
459 * @return previously set firewall policy.
461 public FirewallPolicy getFirewallPolicy();
463 public LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
465 public int updateCall(LinphoneCall call, LinphoneCallParams params);
467 public LinphoneCallParams createDefaultCallParameters();
470 * Sets the path to a wav file used for ringing.
472 * @param path The file must be a wav 16bit linear. Local ring is disabled if null
474 public void setRing(String path);
476 * gets the path to a wav file used for ringing.
478 * @param null if not set
480 public String getRing();
481 public void setUploadBandwidth(int bw);
483 public void setDownloadBandwidth(int bw);
485 public void setPreferredVideoSize(VideoSize vSize);
487 public VideoSize getPreferredVideoSize();