SipAudioCall.java revision 286bb5a00bdb9f0cb0815aef441ec72f231c84ea
1/* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.net.sip; 18 19import android.net.rtp.AudioGroup; 20import android.net.rtp.AudioStream; 21import android.os.Message; 22 23/** 24 * Interface for making audio calls over SIP. 25 * @hide 26 */ 27public interface SipAudioCall { 28 /** Listener class for all event callbacks. */ 29 public interface Listener { 30 /** 31 * Called when the call object is ready to make another call. 32 * 33 * @param call the call object that is ready to make another call 34 */ 35 void onReadyToCall(SipAudioCall call); 36 37 /** 38 * Called when a request is sent out to initiate a new call. 39 * 40 * @param call the call object that carries out the audio call 41 */ 42 void onCalling(SipAudioCall call); 43 44 /** 45 * Called when a new call comes in. 46 * 47 * @param call the call object that carries out the audio call 48 * @param caller the SIP profile of the caller 49 */ 50 void onRinging(SipAudioCall call, SipProfile caller); 51 52 /** 53 * Called when a RINGING response is received for the INVITE request sent 54 * 55 * @param call the call object that carries out the audio call 56 */ 57 void onRingingBack(SipAudioCall call); 58 59 /** 60 * Called when the session is established. 61 * 62 * @param call the call object that carries out the audio call 63 */ 64 void onCallEstablished(SipAudioCall call); 65 66 /** 67 * Called when the session is terminated. 68 * 69 * @param call the call object that carries out the audio call 70 */ 71 void onCallEnded(SipAudioCall call); 72 73 /** 74 * Called when the peer is busy during session initialization. 75 * 76 * @param call the call object that carries out the audio call 77 */ 78 void onCallBusy(SipAudioCall call); 79 80 /** 81 * Called when the call is on hold. 82 * 83 * @param call the call object that carries out the audio call 84 */ 85 void onCallHeld(SipAudioCall call); 86 87 /** 88 * Called when an error occurs. 89 * 90 * @param call the call object that carries out the audio call 91 * @param errorCode error code of this error 92 * @param errorMessage error message 93 */ 94 void onError(SipAudioCall call, SipErrorCode errorCode, 95 String errorMessage); 96 } 97 98 /** 99 * The adapter class for {@link Listener}. The default implementation of 100 * all callback methods is no-op. 101 */ 102 public class Adapter implements Listener { 103 protected void onChanged(SipAudioCall call) { 104 } 105 public void onReadyToCall(SipAudioCall call) { 106 onChanged(call); 107 } 108 public void onCalling(SipAudioCall call) { 109 onChanged(call); 110 } 111 public void onRinging(SipAudioCall call, SipProfile caller) { 112 onChanged(call); 113 } 114 public void onRingingBack(SipAudioCall call) { 115 onChanged(call); 116 } 117 public void onCallEstablished(SipAudioCall call) { 118 onChanged(call); 119 } 120 public void onCallEnded(SipAudioCall call) { 121 onChanged(call); 122 } 123 public void onCallBusy(SipAudioCall call) { 124 onChanged(call); 125 } 126 public void onCallHeld(SipAudioCall call) { 127 onChanged(call); 128 } 129 public void onError(SipAudioCall call, SipErrorCode errorCode, 130 String errorMessage) { 131 onChanged(call); 132 } 133 } 134 135 /** 136 * Sets the listener to listen to the audio call events. The method calls 137 * {@code setListener(listener, false)}. 138 * 139 * @param listener to listen to the audio call events of this object 140 * @see #setListener(Listener, boolean) 141 */ 142 void setListener(Listener listener); 143 144 /** 145 * Sets the listener to listen to the audio call events. A 146 * {@link SipAudioCall} can only hold one listener at a time. Subsequent 147 * calls to this method override the previous listener. 148 * 149 * @param listener to listen to the audio call events of this object 150 * @param callbackImmediately set to true if the caller wants to be called 151 * back immediately on the current state 152 */ 153 void setListener(Listener listener, boolean callbackImmediately); 154 155 /** 156 * Closes this object. The object is not usable after being closed. 157 */ 158 void close(); 159 160 /** 161 * Initiates an audio call to the specified profile. 162 * 163 * @param callee the SIP profile to make the call to 164 * @param sipManager the {@link SipManager} object to help make call with 165 */ 166 void makeCall(SipProfile callee, SipManager sipManager) throws SipException; 167 168 /** 169 * Attaches an incoming call to this call object. 170 * 171 * @param session the session that receives the incoming call 172 * @param sessionDescription the session description of the incoming call 173 */ 174 void attachCall(ISipSession session, String sessionDescription) 175 throws SipException; 176 177 /** Ends a call. */ 178 void endCall() throws SipException; 179 180 /** 181 * Puts a call on hold. When succeeds, {@link Listener#onCallHeld} is 182 * called. 183 */ 184 void holdCall() throws SipException; 185 186 /** Answers a call. */ 187 void answerCall() throws SipException; 188 189 /** 190 * Continues a call that's on hold. When succeeds, 191 * {@link Listener#onCallEstablished} is called. 192 */ 193 void continueCall() throws SipException; 194 195 /** Puts the device to speaker mode. */ 196 void setSpeakerMode(boolean speakerMode); 197 198 /** Toggles mute. */ 199 void toggleMute(); 200 201 /** 202 * Checks if the call is on hold. 203 * 204 * @return true if the call is on hold 205 */ 206 boolean isOnHold(); 207 208 /** 209 * Checks if the call is muted. 210 * 211 * @return true if the call is muted 212 */ 213 boolean isMuted(); 214 215 /** 216 * Sends a DTMF code. 217 * 218 * @param code the DTMF code to send 219 */ 220 void sendDtmf(int code); 221 222 /** 223 * Sends a DTMF code. 224 * 225 * @param code the DTMF code to send 226 * @param result the result message to send when done 227 */ 228 void sendDtmf(int code, Message result); 229 230 /** 231 * Gets the {@link AudioStream} object used in this call. The object 232 * represents the RTP stream that carries the audio data to and from the 233 * peer. The object may not be created before the call is established. And 234 * it is undefined after the call ends or the {@link #close} method is 235 * called. 236 * 237 * @return the {@link AudioStream} object or null if the RTP stream has not 238 * yet been set up 239 */ 240 AudioStream getAudioStream(); 241 242 /** 243 * Gets the {@link AudioGroup} object which the {@link AudioStream} object 244 * joins. The group object may not exist before the call is established. 245 * Also, the {@code AudioStream} may change its group during a call (e.g., 246 * after the call is held/un-held). Finally, the {@code AudioGroup} object 247 * returned by this method is undefined after the call ends or the 248 * {@link #close} method is called. If a group object is set by 249 * {@link #setAudioGroup(AudioGroup)}, then this method returns that object. 250 * 251 * @return the {@link AudioGroup} object or null if the RTP stream has not 252 * yet been set up 253 * @see #getAudioStream 254 */ 255 AudioGroup getAudioGroup(); 256 257 /** 258 * Sets the {@link AudioGroup} object which the {@link AudioStream} object 259 * joins. If {@code audioGroup} is null, then the {@code AudioGroup} object 260 * will be dynamically created when needed. 261 * 262 * @see #getAudioStream 263 */ 264 void setAudioGroup(AudioGroup audioGroup); 265 266 /** 267 * Checks if the call is established. 268 * 269 * @return true if the call is established 270 */ 271 boolean isInCall(); 272 273 /** 274 * Gets the local SIP profile. 275 * 276 * @return the local SIP profile 277 */ 278 SipProfile getLocalProfile(); 279 280 /** 281 * Gets the peer's SIP profile. 282 * 283 * @return the peer's SIP profile 284 */ 285 SipProfile getPeerProfile(); 286 287 /** 288 * Gets the state of the {@link ISipSession} that carries this call. 289 * 290 * @return the session state 291 */ 292 SipSessionState getState(); 293 294 /** 295 * Gets the {@link ISipSession} that carries this call. 296 * 297 * @return the session object that carries this call 298 */ 299 ISipSession getSipSession(); 300 301 /** 302 * Enables/disables the ring-back tone. 303 * 304 * @param enabled true to enable; false to disable 305 */ 306 void setRingbackToneEnabled(boolean enabled); 307 308 /** 309 * Enables/disables the ring tone. 310 * 311 * @param enabled true to enable; false to disable 312 */ 313 void setRingtoneEnabled(boolean enabled); 314} 315