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 * Object representing a Call. calls are created using {@link LinphoneCore#invite(LinphoneAddress)} or passed to the application by listener {@link LinphoneCoreListener#callState(LinphoneCore, LinphoneCall, State, String)}
28 public interface LinphoneCall {
30 * Linphone call states
35 static private Vector values = new Vector();
36 private final int mValue;
37 public final int value() {return mValue;}
39 private final String mStringValue;
43 public final static State Idle = new State(0,"Idle");
45 * Incoming call received.
47 public final static State IncomingReceived = new State(1,"IncomingReceived");
49 * Outgoing call initialiazed.
51 public final static State OutgoingInit = new State(2,"OutgoingInit");
53 * Outgoing call in progress.
55 public final static State OutgoingProgress = new State(3,"OutgoingProgress");
57 * Outgoing call ringing.
59 public final static State OutgoingRinging = new State(4,"OutgoingRinging");
61 * Outgoing call early media
63 public final static State OutgoingEarlyMedia = new State(5,"OutgoingEarlyMedia");
67 public final static State Connected = new State(6,"Connected");
71 public final static State StreamsRunning = new State(7,"StreamsRunning");
75 public final static State Pausing = new State(8,"Pausing");
79 public final static State Paused = new State(9,"Paused");
83 public final static State Resuming = new State(10,"Resuming");
87 public final static State Refered = new State(11,"Refered");
91 public final static State Error = new State(12,"Error");
95 public final static State CallEnd = new State(13,"CallEnd");
100 public final static State PausedByRemote = new State(14,"PausedByRemote");
103 * The call's parameters are updated, used for example when video is asked by remote
105 public static final State CallUpdatedByRemote = new State(15, "CallUpdatedByRemote");
108 * We are proposing early media to an incoming call
110 public static final State CallIncomingEarlyMedia = new State(16,"CallIncomingEarlyMedia");
113 * The remote accepted the call update initiated by us
115 public static final State CallUpdated = new State(17, "CallUpdated");
118 * The call object is now released.
120 public static final State CallReleased = new State(18,"CallReleased");
123 private State(int value,String stringValue) {
125 values.addElement(this);
126 mStringValue=stringValue;
129 public static State fromInt(int value) {
131 for (int i=0; i<values.size();i++) {
132 State state = (State) values.elementAt(i);
133 if (state.mValue == value) return state;
135 throw new RuntimeException("state not found ["+value+"]");
137 public String toString() {
143 * Retrieves the call's current state.
148 * Returns the remote address associated to this call
151 LinphoneAddress getRemoteAddress();
153 * get direction of the call (incoming or outgoing).
154 * @return CallDirection
156 CallDirection getDirection();
158 * get the call log associated to this call.
159 * @Return LinphoneCallLog
161 LinphoneCallLog getCallLog();
163 LinphoneCallParams getRemoteParams();
165 LinphoneCallParams getCurrentParamsCopy();
167 void enableCamera(boolean enabled);
168 boolean cameraEnabled();
171 * Enables or disable echo cancellation.
174 void enableEchoCancellation(boolean enable);
177 * @return true if echo cancellation is enabled.
179 boolean isEchoCancellationEnabled();
181 * Enables or disable echo limiter cancellation.
184 void enableEchoLimiter(boolean enable);
187 * @return true if echo limiter is enabled.
189 boolean isEchoLimiterEnabled();
191 * Returns the object associated to a call this one is replacing.
192 * Call replacement can occur during transfer scenarios.
194 LinphoneCall getReplacedCall();
197 * @return call duration computed from media start
201 * Obtain real-time quality rating of the call
203 * Based on local RTP statistics and RTCP feedback, a quality rating is computed and updated
204 * during all the duration of the call. This function returns its value at the time of the function call.
205 * It is expected that the rating is updated at least every 5 seconds or so.
206 * The rating is a floating point number comprised between 0 and 5.
208 * 4-5 = good quality <br>
209 * 3-4 = average quality <br>
210 * 2-3 = poor quality <br>
211 * 1-2 = very poor quality <br>
212 * 0-1 = can't be worse, mostly unusable <br>
214 * @returns The function returns -1 if no quality measurement is available, for example if no
215 * active audio stream exist. Otherwise it returns the quality rating.
217 float getCurrentQuality();
219 * Returns call quality averaged over all the duration of the call.
221 * See getCurrentQuality() for more details about quality measurement.
223 float getAverageQuality();
226 * Used by ZRTP encryption mechanism.
227 * @return SAS associated to the main stream [voice]
229 String getAuthenticationToken();
232 * Used by ZRTP encryption mechanism.
233 * SAS can be verified manually by the user or automatically using a previously shared secret.
234 * @return true if the main stream [voice ]SAS was verified.
236 boolean isAuthenticationTokenVerified();
239 * Used by ZRTP encryption mechanism.
240 * @param verified true when displayed SAS is correct
242 void setAuthenticationTokenVerified(boolean verified);
244 boolean isInConference();
246 float getPlayVolume();