SipAudioCall.java revision 95b15c35608fe3ea679c8a478c6cbd841623371e 
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 sessionDescription the session description of the incoming call
172     */
173    void attachCall(ISipSession session, String sessionDescription)
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. If a group object is set by
248     * {@link #setAudioGroup(AudioGroup)}, then this method returns that object.
249     *
250     * @return the {@link AudioGroup} object or null if the RTP stream has not
251     *      yet been set up
252     * @see #getAudioStream
253     */
254    AudioGroup getAudioGroup();
255
256    /**
257     * Sets the {@link AudioGroup} object which the {@link AudioStream} object
258     * joins. If {@code audioGroup} is null, then the {@code AudioGroup} object
259     * will be dynamically created when needed.
260     *
261     * @see #getAudioStream
262     */
263    void setAudioGroup(AudioGroup audioGroup);
264
265    /**
266     * Checks if the call is established.
267     *
268     * @return true if the call is established
269     */
270    boolean isInCall();
271
272    /**
273     * Gets the local SIP profile.
274     *
275     * @return the local SIP profile
276     */
277    SipProfile getLocalProfile();
278
279    /**
280     * Gets the peer's SIP profile.
281     *
282     * @return the peer's SIP profile
283     */
284    SipProfile getPeerProfile();
285
286    /**
287     * Gets the state of the {@link ISipSession} that carries this call.
288     *
289     * @return the session state
290     */
291    SipSessionState getState();
292
293    /**
294     * Gets the {@link ISipSession} that carries this call.
295     *
296     * @return the session object that carries this call
297     */
298    ISipSession getSipSession();
299
300    /**
301     * Enables/disables the ring-back tone.
302     *
303     * @param enabled true to enable; false to disable
304     */
305    void setRingbackToneEnabled(boolean enabled);
306
307    /**
308     * Enables/disables the ring tone.
309     *
310     * @param enabled true to enable; false to disable
311     */
312    void setRingtoneEnabled(boolean enabled);
313}
314