SipAudioCall.java revision 903e1031605d715e904811b0dd06cc6a518f0048 
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 errorCode error code defined in {@link SipErrorCode}
94         * @param errorMessage error message
95         */
96        void onError(SipAudioCall call, String errorCode, String errorMessage);
97    }
98
99    /**
100     * The adapter class for {@link SipAudioCall#Listener}. The default
101     * implementation of all callback methods is no-op.
102     */
103    public class Adapter implements Listener {
104        protected void onChanged(SipAudioCall call) {
105        }
106        public void onReadyToCall(SipAudioCall call) {
107            onChanged(call);
108        }
109        public void onCalling(SipAudioCall call) {
110            onChanged(call);
111        }
112        public void onRinging(SipAudioCall call, SipProfile caller) {
113            onChanged(call);
114        }
115        public void onRingingBack(SipAudioCall call) {
116            onChanged(call);
117        }
118        public void onCallEstablished(SipAudioCall call) {
119            onChanged(call);
120        }
121        public void onCallEnded(SipAudioCall call) {
122            onChanged(call);
123        }
124        public void onCallBusy(SipAudioCall call) {
125            onChanged(call);
126        }
127        public void onCallHeld(SipAudioCall call) {
128            onChanged(call);
129        }
130        public void onError(SipAudioCall call, String errorCode,
131                String errorMessage) {
132            onChanged(call);
133        }
134    }
135
136    /**
137     * Sets the listener to listen to the audio call events. The method calls
138     * {@link #setListener(Listener, false)}.
139     *
140     * @param listener to listen to the audio call events of this object
141     * @see #setListener(Listener, boolean)
142     */
143    void setListener(Listener listener);
144
145    /**
146     * Sets the listener to listen to the audio call events. A
147     * {@link SipAudioCall} can only hold one listener at a time. Subsequent
148     * calls to this method override the previous listener.
149     *
150     * @param listener to listen to the audio call events of this object
151     * @param callbackImmediately set to true if the caller wants to be called
152     *      back immediately on the current state
153     */
154    void setListener(Listener listener, boolean callbackImmediately);
155
156    /**
157     * Closes this object. The object is not usable after being closed.
158     */
159    void close();
160
161    /**
162     * Initiates an audio call to the specified profile.
163     *
164     * @param callee the SIP profile to make the call to
165     * @param sipManager the {@link SipManager} object to help make call with
166     */
167    void makeCall(SipProfile callee, SipManager sipManager) throws SipException;
168
169    /**
170     * Attaches an incoming call to this call object.
171     *
172     * @param session the session that receives the incoming call
173     * @param sessionDescription the session description of the incoming call
174     */
175    void attachCall(ISipSession session, String sessionDescription)
176            throws SipException;
177
178    /** Ends a call. */
179    void endCall() throws SipException;
180
181    /**
182     * Puts a call on hold.  When succeeds,
183     * {@link #Listener#onCallHeld(SipAudioCall)} is called.
184     */
185    void holdCall() throws SipException;
186
187    /** Answers a call. */
188    void answerCall() throws SipException;
189
190    /**
191     * Continues a call that's on hold. When succeeds,
192     * {@link #Listener#onCallEstablished(SipAudioCall)} is called.
193     */
194    void continueCall() throws SipException;
195
196    /** Puts the device to speaker mode. */
197    void setSpeakerMode(boolean speakerMode);
198
199    /** Toggles mute. */
200    void toggleMute();
201
202    /**
203     * Checks if the call is on hold.
204     *
205     * @return true if the call is on hold
206     */
207    boolean isOnHold();
208
209    /**
210     * Checks if the call is muted.
211     *
212     * @return true if the call is muted
213     */
214    boolean isMuted();
215
216    /**
217     * Sends a DTMF code.
218     *
219     * @param code the DTMF code to send
220     */
221    void sendDtmf(int code);
222
223    /**
224     * Sends a DTMF code.
225     *
226     * @param code the DTMF code to send
227     * @param result the result message to send when done
228     */
229    void sendDtmf(int code, Message result);
230
231    /**
232     * Gets the {@link AudioStream} object used in this call. The object
233     * represents the RTP stream that carries the audio data to and from the
234     * peer. The object may not be created before the call is established. And
235     * it is undefined after the call ends or the {@link #close} method is
236     * called.
237     *
238     * @return the {@link AudioStream} object or null if the RTP stream has not
239     *      yet been set up
240     */
241    AudioStream getAudioStream();
242
243    /**
244     * Gets the {@link AudioGroup} object which the {@link AudioStream} object
245     * joins. The group object may not exist before the call is established.
246     * Also, the {@code AudioStream} may change its group during a call (e.g.,
247     * after the call is held/un-held). Finally, the {@code AudioGroup} object
248     * returned by this method is undefined after the call ends or the
249     * {@link #close} method is called. If a group object is set by
250     * {@link #setAudioGroup(AudioGroup)}, then this method returns that object.
251     *
252     * @return the {@link AudioGroup} object or null if the RTP stream has not
253     *      yet been set up
254     * @see #getAudioStream
255     */
256    AudioGroup getAudioGroup();
257
258    /**
259     * Sets the {@link AudioGroup} object which the {@link AudioStream} object
260     * joins. If {@code audioGroup} is null, then the {@code AudioGroup} object
261     * will be dynamically created when needed.
262     *
263     * @see #getAudioStream
264     */
265    void setAudioGroup(AudioGroup audioGroup);
266
267    /**
268     * Checks if the call is established.
269     *
270     * @return true if the call is established
271     */
272    boolean isInCall();
273
274    /**
275     * Gets the local SIP profile.
276     *
277     * @return the local SIP profile
278     */
279    SipProfile getLocalProfile();
280
281    /**
282     * Gets the peer's SIP profile.
283     *
284     * @return the peer's SIP profile
285     */
286    SipProfile getPeerProfile();
287
288    /**
289     * Gets the state of the {@link ISipSession} that carries this call.
290     *
291     * @return the session state
292     */
293    SipSessionState getState();
294
295    /**
296     * Gets the {@link ISipSession} that carries this call.
297     *
298     * @return the session object that carries this call
299     */
300    ISipSession getSipSession();
301
302    /**
303     * Enables/disables the ring-back tone.
304     *
305     * @param enabled true to enable; false to disable
306     */
307    void setRingbackToneEnabled(boolean enabled);
308
309    /**
310     * Enables/disables the ring tone.
311     *
312     * @param enabled true to enable; false to disable
313     */
314    void setRingtoneEnabled(boolean enabled);
315}
316