SipAudioCall.java revision afa583e6557557577188c3e40146ac8d6f2aa7c7 
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. This object is not usable after being closed.
157     */
158    void close();
159
160    /**
161     * Initiates an audio call to the specified profile. The attempt will be
162     * timed out if the call is not established within {@code timeout} seconds
163     * and {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
164     * will be called.
165     *
166     * @param callee the SIP profile to make the call to
167     * @param sipManager the {@link SipManager} object to help make call with
168     * @param timeout the timeout value in seconds
169     * @see Listener.onError
170     */
171    void makeCall(SipProfile callee, SipManager sipManager, int timeout)
172            throws SipException;
173
174    /**
175     * Starts the audio for the established call. This method should be called
176     * after {@link Listener#onCallEstablished} is called.
177     */
178    void startAudio();
179
180    /**
181     * Attaches an incoming call to this call object.
182     *
183     * @param session the session that receives the incoming call
184     * @param sessionDescription the session description of the incoming call
185     */
186    void attachCall(ISipSession session, String sessionDescription)
187            throws SipException;
188
189    /** Ends a call. */
190    void endCall() throws SipException;
191
192    /**
193     * Puts a call on hold.  When succeeds, {@link Listener#onCallHeld} is
194     * called. The attempt will be timed out if the call is not established
195     * within {@code timeout} seconds and
196     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
197     * will be called.
198     *
199     * @param timeout the timeout value in seconds
200     * @see Listener.onError
201     */
202    void holdCall(int timeout) throws SipException;
203
204    /**
205     * Answers a call. The attempt will be timed out if the call is not
206     * established within {@code timeout} seconds and
207     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
208     * will be called.
209     *
210     * @param timeout the timeout value in seconds
211     * @see Listener.onError
212     */
213    void answerCall(int timeout) throws SipException;
214
215    /**
216     * Continues a call that's on hold. When succeeds,
217     * {@link Listener#onCallEstablished} is called. The attempt will be timed
218     * out if the call is not established within {@code timeout} seconds and
219     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
220     * will be called.
221     *
222     * @param timeout the timeout value in seconds
223     * @see Listener.onError
224     */
225    void continueCall(int timeout) throws SipException;
226
227    /** Puts the device to speaker mode. */
228    void setSpeakerMode(boolean speakerMode);
229
230    /** Toggles mute. */
231    void toggleMute();
232
233    /**
234     * Checks if the call is on hold.
235     *
236     * @return true if the call is on hold
237     */
238    boolean isOnHold();
239
240    /**
241     * Checks if the call is muted.
242     *
243     * @return true if the call is muted
244     */
245    boolean isMuted();
246
247    /**
248     * Sends a DTMF code.
249     *
250     * @param code the DTMF code to send
251     */
252    void sendDtmf(int code);
253
254    /**
255     * Sends a DTMF code.
256     *
257     * @param code the DTMF code to send
258     * @param result the result message to send when done
259     */
260    void sendDtmf(int code, Message result);
261
262    /**
263     * Gets the {@link AudioStream} object used in this call. The object
264     * represents the RTP stream that carries the audio data to and from the
265     * peer. The object may not be created before the call is established. And
266     * it is undefined after the call ends or the {@link #close} method is
267     * called.
268     *
269     * @return the {@link AudioStream} object or null if the RTP stream has not
270     *      yet been set up
271     */
272    AudioStream getAudioStream();
273
274    /**
275     * Gets the {@link AudioGroup} object which the {@link AudioStream} object
276     * joins. The group object may not exist before the call is established.
277     * Also, the {@code AudioStream} may change its group during a call (e.g.,
278     * after the call is held/un-held). Finally, the {@code AudioGroup} object
279     * returned by this method is undefined after the call ends or the
280     * {@link #close} method is called. If a group object is set by
281     * {@link #setAudioGroup(AudioGroup)}, then this method returns that object.
282     *
283     * @return the {@link AudioGroup} object or null if the RTP stream has not
284     *      yet been set up
285     * @see #getAudioStream
286     */
287    AudioGroup getAudioGroup();
288
289    /**
290     * Sets the {@link AudioGroup} object which the {@link AudioStream} object
291     * joins. If {@code audioGroup} is null, then the {@code AudioGroup} object
292     * will be dynamically created when needed.
293     *
294     * @see #getAudioStream
295     */
296    void setAudioGroup(AudioGroup audioGroup);
297
298    /**
299     * Checks if the call is established.
300     *
301     * @return true if the call is established
302     */
303    boolean isInCall();
304
305    /**
306     * Gets the local SIP profile.
307     *
308     * @return the local SIP profile
309     */
310    SipProfile getLocalProfile();
311
312    /**
313     * Gets the peer's SIP profile.
314     *
315     * @return the peer's SIP profile
316     */
317    SipProfile getPeerProfile();
318
319    /**
320     * Gets the state of the {@link ISipSession} that carries this call.
321     *
322     * @return the session state
323     */
324    SipSessionState getState();
325
326    /**
327     * Gets the {@link ISipSession} that carries this call.
328     *
329     * @return the session object that carries this call
330     */
331    ISipSession getSipSession();
332
333    /**
334     * Enables/disables the ring-back tone.
335     *
336     * @param enabled true to enable; false to disable
337     */
338    void setRingbackToneEnabled(boolean enabled);
339
340    /**
341     * Enables/disables the ring tone.
342     *
343     * @param enabled true to enable; false to disable
344     */
345    void setRingtoneEnabled(boolean enabled);
346}
347