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