sjero.net Git - linphone/blob - java/common/org/linphone/core/LinphoneCall.java

   1 /*
   2 LinphoneCall.java
   3 Copyright (C) 2010  Belledonne Communications, Grenoble, France
   4
   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.
   9
  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.
  14
  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.
  18 */
  19 package org.linphone.core;
  20
  21 import java.util.Vector;
  22
  23 /**
  24  * Object representing a call. Calls are created using {@link LinphoneCore#invite(LinphoneAddress)} or passed to the application by listener {@link LinphoneCoreListener#callState}
  25  *
  26  */
  27
  28 public interface LinphoneCall {
  29         /**
  30          * Linphone call states
  31          *
  32          */
  33         static class State {
  34
  35                 static private Vector<State> values = new Vector<State>();
  36                 private final int mValue;
  37                 public final int value() {return mValue;}
  38
  39                 private final String mStringValue;
  40                 /**
  41                  * Idle
  42                  */
  43                 public final static State Idle = new State(0,"Idle");
  44                 /**
  45                  * Incoming call received.
  46                  */
  47                 public final static State IncomingReceived = new State(1,"IncomingReceived");
  48                 /**
  49                  * Outgoing call initialiazed.
  50                  */
  51                 public final static State OutgoingInit = new State(2,"OutgoingInit");
  52                 /**
  53                  * Outgoing call in progress.
  54                  */
  55                 public final static State OutgoingProgress = new State(3,"OutgoingProgress");
  56                 /**
  57                  * Outgoing call ringing.
  58                  */
  59                 public final static State OutgoingRinging = new State(4,"OutgoingRinging");
  60                 /**
  61                  * Outgoing call early media
  62                  */
  63                 public final static State OutgoingEarlyMedia = new State(5,"OutgoingEarlyMedia");
  64                 /**
  65                  * Connected
  66                  */
  67                 public final static State Connected = new State(6,"Connected");
  68                 /**
  69                  * Streams running
  70                  */
  71                 public final static State StreamsRunning = new State(7,"StreamsRunning");
  72                 /**
  73                  * Pausing
  74                  */
  75                 public final static State Pausing = new State(8,"Pausing");
  76                 /**
  77                  * Paused
  78                  */
  79                 public final static State Paused = new State(9,"Paused");
  80                 /**
  81                  * Resuming
  82                  */
  83                 public final static State Resuming = new State(10,"Resuming");
  84                 /**
  85                  * Refered
  86                  */
  87                 public final static State Refered = new State(11,"Refered");
  88                 /**
  89                  * Error
  90                  */
  91                 public final static State Error = new State(12,"Error");
  92                 /**
  93                  * Call end
  94                  */
  95                 public final static State CallEnd = new State(13,"CallEnd");
  96
  97                 /**
  98                  * Paused by remote
  99                  */
 100                 public final static State PausedByRemote = new State(14,"PausedByRemote");
 101
 102                 /**
 103                  * The call's parameters are updated, used for example when video is asked by remote
 104                  */
 105                 public static final State CallUpdatedByRemote = new State(15, "UpdatedByRemote");
 106
 107                 /**
 108                  * We are proposing early media to an incoming call
 109                  */
 110                 public static final State CallIncomingEarlyMedia = new State(16,"IncomingEarlyMedia");
 111
 112                 /**
 113                  * We have initiated a call update. When the remote accepts the call update, state will move to StreamsRunning.
 114                  */
 115                 public static final State CallUpdating = new State(17, "Updating");
 116
 117                 /**
 118                  * The call object is now released.
 119                  */
 120                 public static final State CallReleased = new State(18,"Released");
 121
 122
 123                 private State(int value,String stringValue) {
 124                         mValue = value;
 125                         values.addElement(this);
 126                         mStringValue=stringValue;
 127                 }
 128
 129                 public static State fromInt(int value) {
 130
 131                         for (int i=0; i<values.size();i++) {
 132                                 State state = (State) values.elementAt(i);
 133                                 if (state.mValue == value) return state;
 134                         }
 135                         throw new RuntimeException("state not found ["+value+"]");
 136                 }
 137                 public String toString() {
 138                         return mStringValue;
 139                 }
 140         }
 141
 142         /**
 143          * Retrieves the call's current state.
 144         **/
 145         State getState();
 146
 147         /**
 148          * Returns the remote address associated to this call
 149          *
 150         **/
 151         LinphoneAddress  getRemoteAddress();
 152         /**
 153          * get direction of the call (incoming or outgoing).
 154          * @return CallDirection
 155          */
 156         CallDirection getDirection();
 157         /**
 158          * get the call log associated to this call.
 159          * @Return LinphoneCallLog
 160         **/
 161         LinphoneCallLog getCallLog();
 162
 163
 164         /**
 165          * Get the audio statistics associated with this call.
 166          * @return LinphoneCallStats
 167          */
 168         LinphoneCallStats getAudioStats();
 169
 170         /**
 171          * Get the video statistics associated with this call.
 172          * @return LinphoneCallStats
 173          */
 174         LinphoneCallStats getVideoStats();
 175
 176         /**
 177          * Get call's remote parameters, as proposed by far end.
 178          * This is useful for example to know if far end supports video or encryption.
 179         **/
 180         LinphoneCallParams getRemoteParams();
 181
 182         LinphoneCallParams getCurrentParamsCopy();
 183
 184         void enableCamera(boolean enabled);
 185         boolean cameraEnabled();
 186
 187         /**
 188          * Enables or disable echo cancellation.
 189          * @param enable
 190          */
 191         void enableEchoCancellation(boolean enable);
 192         /**
 193          * get EC status
 194          * @return true if echo cancellation is enabled.
 195          */
 196         boolean isEchoCancellationEnabled();
 197         /**
 198          * Enables or disable echo limiter cancellation.
 199          * @param enable
 200          */
 201         void enableEchoLimiter(boolean enable);
 202         /**
 203          * get EL status
 204          * @return true if echo limiter is enabled.
 205          */
 206         boolean isEchoLimiterEnabled();
 207         /**
 208          * Returns the object associated to a call this one is replacing.
 209          * Call replacement can occur during transfer scenarios.
 210          */
 211         LinphoneCall getReplacedCall();
 212
 213         /**
 214          * @return call duration computed from media start
 215          */
 216         int getDuration();
 217         /**
 218          * Obtain real-time quality rating of the call
 219          *
 220          * Based on local RTP statistics and RTCP feedback, a quality rating is computed and updated
 221          * during all the duration of the call. This function returns its value at the time of the function call.
 222          * It is expected that the rating is updated at least every 5 seconds or so.
 223          * The rating is a floating point number comprised between 0 and 5.
 224          *
 225          * 4-5 = good quality <br>
 226          * 3-4 = average quality <br>
 227          * 2-3 = poor quality <br>
 228          * 1-2 = very poor quality <br>
 229          * 0-1 = can't be worse, mostly unusable <br>
 230          *
 231          * @returns The function returns -1 if no quality measurement is available, for example if no
 232          * active audio stream exist. Otherwise it returns the quality rating.
 233          */
 234         float getCurrentQuality();
 235         /**
 236          * Returns call quality averaged over all the duration of the call.
 237          *
 238          * See getCurrentQuality() for more details about quality measurement.
 239          */
 240         float getAverageQuality();
 241
 242         /**
 243          * Used by ZRTP encryption mechanism.
 244          * @return SAS associated to the main stream [voice]
 245          */
 246         String getAuthenticationToken();
 247
 248         /**
 249          * Used by ZRTP encryption mechanism.
 250          * SAS can be verified manually by the user or automatically using a previously shared secret.
 251          * @return true if the main stream [voice ]SAS was verified.
 252          */
 253         boolean isAuthenticationTokenVerified();
 254
 255         /**
 256          * Used by ZRTP encryption mechanism.
 257          * @param verified true when displayed SAS is correct
 258          */
 259         void setAuthenticationTokenVerified(boolean verified);
 260
 261         boolean isInConference();
 262
 263         float getPlayVolume();
 264
 265         /**
 266          * Obtain the remote user agent string.
 267          */
 268         String getRemoteUserAgent();
 269
 270         /**
 271          * Obtain the remote sip contact string.
 272         **/
 273         String getRemoteContact();
 274
 275         /**
 276          * Take a photo of currently received video and write it into a jpeg file.
 277          */
 278         void takeSnapshot(String path);
 279
 280         /**
 281          * Scale the video by factor, and center it using cx,cy point
 282          */
 283         void zoomVideo(float factor, float cx, float cy);
 284 }