SipAudioCall.java revision cfd15dd3c8554cbbcb5822a0fdf6ca31d6b28acf
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 23import javax.sip.SipException; 24 25/** 26 * Interface for making audio calls over SIP. 27 * @hide 28 */ 29public interface SipAudioCall { 30 /** Listener class for all event callbacks. */ 31 public interface Listener { 32 /** 33 * Called when the call object is ready to make another call. 34 * 35 * @param call the call object that is ready to make another call 36 */ 37 void onReadyToCall(SipAudioCall call); 38 39 /** 40 * Called when a request is sent out to initiate a new call. 41 * 42 * @param call the call object that carries out the audio call 43 */ 44 void onCalling(SipAudioCall call); 45 46 /** 47 * Called when a new call comes in. 48 * 49 * @param call the call object that carries out the audio call 50 * @param caller the SIP profile of the caller 51 */ 52 void onRinging(SipAudioCall call, SipProfile caller); 53 54 /** 55 * Called when a RINGING response is received for the INVITE request sent 56 * 57 * @param call the call object that carries out the audio call 58 */ 59 void onRingingBack(SipAudioCall call); 60 61 /** 62 * Called when the session is established. 63 * 64 * @param call the call object that carries out the audio call 65 */ 66 void onCallEstablished(SipAudioCall call); 67 68 /** 69 * Called when the session is terminated. 70 * 71 * @param call the call object that carries out the audio call 72 */ 73 void onCallEnded(SipAudioCall call); 74 75 /** 76 * Called when the peer is busy during session initialization. 77 * 78 * @param call the call object that carries out the audio call 79 */ 80 void onCallBusy(SipAudioCall call); 81 82 /** 83 * Called when the call is on hold. 84 * 85 * @param call the call object that carries out the audio call 86 */ 87 void onCallHeld(SipAudioCall call); 88 89 /** 90 * Called when an error occurs. 91 * 92 * @param call the call object that carries out the audio call 93 * @param errorMessage error message 94 */ 95 void onError(SipAudioCall call, String errorMessage); 96 } 97 98 /** 99 * The adapter class for {@link SipAudioCall#Listener}. The default 100 * implementation of 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, String errorMessage) { 130 onChanged(call); 131 } 132 } 133 134 /** 135 * Sets the listener to listen to the audio call events. The method calls 136 * {@link #setListener(Listener, false)}. 137 * 138 * @param listener to listen to the audio call events of this object 139 * @see #setListener(Listener, boolean) 140 */ 141 void setListener(Listener listener); 142 143 /** 144 * Sets the listener to listen to the audio call events. A 145 * {@link SipAudioCall} can only hold one listener at a time. Subsequent 146 * calls to this method override the previous listener. 147 * 148 * @param listener to listen to the audio call events of this object 149 * @param callbackImmediately set to true if the caller wants to be called 150 * back immediately on the current state 151 */ 152 void setListener(Listener listener, boolean callbackImmediately); 153 154 /** 155 * Closes this object. The object is not usable after being closed. 156 */ 157 void close(); 158 159 /** 160 * Initiates an audio call to the specified profile. 161 * 162 * @param callee the SIP profile to make the call to 163 * @param sipManager the {@link SipManager} object to help make call with 164 */ 165 void makeCall(SipProfile callee, SipManager sipManager) throws SipException; 166 167 /** 168 * Attaches an incoming call to this call object. 169 * 170 * @param session the session that receives the incoming call 171 * @param sdp the session description of the incoming call 172 */ 173 void attachCall(ISipSession session, SdpSessionDescription sdp) 174 throws SipException; 175 176 /** Ends a call. */ 177 void endCall() throws SipException; 178 179 /** 180 * Puts a call on hold. When succeeds, 181 * {@link #Listener#onCallHeld(SipAudioCall)} is called. 182 */ 183 void holdCall() throws SipException; 184 185 /** Answers a call. */ 186 void answerCall() throws SipException; 187 188 /** 189 * Continues a call that's on hold. When succeeds, 190 * {@link #Listener#onCallEstablished(SipAudioCall)} is called. 191 */ 192 void continueCall() throws SipException; 193 194 /** Puts the device to speaker mode. */ 195 void setSpeakerMode(boolean speakerMode); 196 197 /** Toggles mute. */ 198 void toggleMute(); 199 200 /** 201 * Checks if the call is on hold. 202 * 203 * @return true if the call is on hold 204 */ 205 boolean isOnHold(); 206 207 /** 208 * Checks if the call is muted. 209 * 210 * @return true if the call is muted 211 */ 212 boolean isMuted(); 213 214 /** 215 * Sends a DTMF code. 216 * 217 * @param code the DTMF code to send 218 */ 219 void sendDtmf(int code); 220 221 /** 222 * Sends a DTMF code. 223 * 224 * @param code the DTMF code to send 225 * @param result the result message to send when done 226 */ 227 void sendDtmf(int code, Message result); 228 229 /** 230 * Gets the {@link AudioStream} object used in this call. The object 231 * represents the RTP stream that carries the audio data to and from the 232 * peer. The object may not be created before the call is established. And 233 * it is undefined after the call ends or the {@link #close} method is 234 * called. 235 * 236 * @return the {@link AudioStream} object or null if the RTP stream has not 237 * yet been set up 238 */ 239 AudioStream getAudioStream(); 240 241 /** 242 * Gets the {@link AudioGroup} object which the {@link AudioStream} object 243 * joins. The group object may not exist before the call is established. 244 * Also, the {@code AudioStream} may change its group during a call (e.g., 245 * after the call is held/un-held). Finally, the {@code AudioGroup} object 246 * returned by this method is undefined after the call ends or the 247 * {@link #close} method is called. 248 * 249 * @return the {@link AudioGroup} object or null if the RTP stream has not 250 * yet been set up 251 * @see #getAudioStream 252 */ 253 AudioGroup getAudioGroup(); 254 255 /** 256 * Checks if the call is established. 257 * 258 * @return true if the call is established 259 */ 260 boolean isInCall(); 261 262 /** 263 * Gets the local SIP profile. 264 * 265 * @return the local SIP profile 266 */ 267 SipProfile getLocalProfile(); 268 269 /** 270 * Gets the peer's SIP profile. 271 * 272 * @return the peer's SIP profile 273 */ 274 SipProfile getPeerProfile(); 275 276 /** 277 * Gets the state of the {@link ISipSession} that carries this call. 278 * 279 * @return the session state 280 */ 281 SipSessionState getState(); 282 283 /** 284 * Gets the {@link ISipSession} that carries this call. 285 * 286 * @return the session object that carries this call 287 */ 288 ISipSession getSipSession(); 289 290 /** 291 * Enables/disables the ring-back tone. 292 * 293 * @param enabled true to enable; false to disable 294 */ 295 void setRingbackToneEnabled(boolean enabled); 296 297 /** 298 * Enables/disables the ring tone. 299 * 300 * @param enabled true to enable; false to disable 301 */ 302 void setRingtoneEnabled(boolean enabled); 303} 304