1/*
2 * Copyright (C) 2014 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.telecom;
18
19import android.os.RemoteException;
20
21import com.android.internal.telecom.IInCallAdapter;
22
23/**
24 * Receives commands from {@link InCallService} implementations which should be executed by
25 * Telecom. When Telecom binds to a {@link InCallService}, an instance of this class is given to
26 * the in-call service through which it can manipulate live (active, dialing, ringing) calls. When
27 * the in-call service is notified of new calls, it can use the
28 * given call IDs to execute commands such as {@link #answerCall} for incoming calls or
29 * {@link #disconnectCall} for active calls the user would like to end. Some commands are only
30 * appropriate for calls in certain states; please consult each method for such limitations.
31 * <p>
32 * The adapter will stop functioning when there are no more calls.
33 *
34 * {@hide}
35 */
36public final class InCallAdapter {
37    private final IInCallAdapter mAdapter;
38
39    /**
40     * {@hide}
41     */
42    public InCallAdapter(IInCallAdapter adapter) {
43        mAdapter = adapter;
44    }
45
46    /**
47     * Instructs Telecom to answer the specified call.
48     *
49     * @param callId The identifier of the call to answer.
50     * @param videoState The video state in which to answer the call.
51     */
52    public void answerCall(String callId, int videoState) {
53        try {
54            mAdapter.answerCall(callId, videoState);
55        } catch (RemoteException e) {
56        }
57    }
58
59    /**
60     * Instructs Telecom to reject the specified call.
61     *
62     * @param callId The identifier of the call to reject.
63     * @param rejectWithMessage Whether to reject with a text message.
64     * @param textMessage An optional text message with which to respond.
65     */
66    public void rejectCall(String callId, boolean rejectWithMessage, String textMessage) {
67        try {
68            mAdapter.rejectCall(callId, rejectWithMessage, textMessage);
69        } catch (RemoteException e) {
70        }
71    }
72
73    /**
74     * Instructs Telecom to disconnect the specified call.
75     *
76     * @param callId The identifier of the call to disconnect.
77     */
78    public void disconnectCall(String callId) {
79        try {
80            mAdapter.disconnectCall(callId);
81        } catch (RemoteException e) {
82        }
83    }
84
85    /**
86     * Instructs Telecom to put the specified call on hold.
87     *
88     * @param callId The identifier of the call to put on hold.
89     */
90    public void holdCall(String callId) {
91        try {
92            mAdapter.holdCall(callId);
93        } catch (RemoteException e) {
94        }
95    }
96
97    /**
98     * Instructs Telecom to release the specified call from hold.
99     *
100     * @param callId The identifier of the call to release from hold.
101     */
102    public void unholdCall(String callId) {
103        try {
104            mAdapter.unholdCall(callId);
105        } catch (RemoteException e) {
106        }
107    }
108
109    /**
110     * Mute the microphone.
111     *
112     * @param shouldMute True if the microphone should be muted.
113     */
114    public void mute(boolean shouldMute) {
115        try {
116            mAdapter.mute(shouldMute);
117        } catch (RemoteException e) {
118        }
119    }
120
121    /**
122     * Sets the audio route (speaker, bluetooth, etc...). See {@link CallAudioState}.
123     *
124     * @param route The audio route to use.
125     */
126    public void setAudioRoute(int route) {
127        try {
128            mAdapter.setAudioRoute(route);
129        } catch (RemoteException e) {
130        }
131    }
132
133    /**
134     * Instructs Telecom to play a dual-tone multi-frequency signaling (DTMF) tone in a call.
135     *
136     * Any other currently playing DTMF tone in the specified call is immediately stopped.
137     *
138     * @param callId The unique ID of the call in which the tone will be played.
139     * @param digit A character representing the DTMF digit for which to play the tone. This
140     *         value must be one of {@code '0'} through {@code '9'}, {@code '*'} or {@code '#'}.
141     */
142    public void playDtmfTone(String callId, char digit) {
143        try {
144            mAdapter.playDtmfTone(callId, digit);
145        } catch (RemoteException e) {
146        }
147    }
148
149    /**
150     * Instructs Telecom to stop any dual-tone multi-frequency signaling (DTMF) tone currently
151     * playing.
152     *
153     * DTMF tones are played by calling {@link #playDtmfTone(String,char)}. If no DTMF tone is
154     * currently playing, this method will do nothing.
155     *
156     * @param callId The unique ID of the call in which any currently playing tone will be stopped.
157     */
158    public void stopDtmfTone(String callId) {
159        try {
160            mAdapter.stopDtmfTone(callId);
161        } catch (RemoteException e) {
162        }
163    }
164
165    /**
166     * Instructs Telecom to continue playing a post-dial DTMF string.
167     *
168     * A post-dial DTMF string is a string of digits entered after a phone number, when dialed,
169     * that are immediately sent as DTMF tones to the recipient as soon as the connection is made.
170     * While these tones are playing, Telecom will notify the {@link InCallService} that the call
171     * is in the post dial state.
172     *
173     * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_PAUSE} symbol, Telecom
174     * will temporarily pause playing the tones for a pre-defined period of time.
175     *
176     * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_WAIT} symbol, Telecom
177     * will pause playing the tones and notify the {@link InCallService} that the call is in the
178     * post dial wait state. When the user decides to continue the postdial sequence, the
179     * {@link InCallService} should invoke the {@link #postDialContinue(String,boolean)} method.
180     *
181     * @param callId The unique ID of the call for which postdial string playing should continue.
182     * @param proceed Whether or not to continue with the post-dial sequence.
183     */
184    public void postDialContinue(String callId, boolean proceed) {
185        try {
186            mAdapter.postDialContinue(callId, proceed);
187        } catch (RemoteException e) {
188        }
189    }
190
191    /**
192     * Instructs Telecom to add a PhoneAccountHandle to the specified call.
193     *
194     * @param callId The identifier of the call.
195     * @param accountHandle The PhoneAccountHandle through which to place the call.
196     * @param setDefault {@code True} if this account should be set as the default for calls.
197     */
198    public void phoneAccountSelected(String callId, PhoneAccountHandle accountHandle,
199            boolean setDefault) {
200        try {
201            mAdapter.phoneAccountSelected(callId, accountHandle, setDefault);
202        } catch (RemoteException e) {
203        }
204    }
205
206    /**
207     * Instructs Telecom to conference the specified call.
208     *
209     * @param callId The unique ID of the call.
210     * @hide
211     */
212    public void conference(String callId, String otherCallId) {
213        try {
214            mAdapter.conference(callId, otherCallId);
215        } catch (RemoteException ignored) {
216        }
217    }
218
219    /**
220     * Instructs Telecom to split the specified call from any conference call with which it may be
221     * connected.
222     *
223     * @param callId The unique ID of the call.
224     * @hide
225     */
226    public void splitFromConference(String callId) {
227        try {
228            mAdapter.splitFromConference(callId);
229        } catch (RemoteException ignored) {
230        }
231    }
232
233    /**
234     * Instructs Telecom to merge child calls of the specified conference call.
235     */
236    public void mergeConference(String callId) {
237        try {
238            mAdapter.mergeConference(callId);
239        } catch (RemoteException ignored) {
240        }
241    }
242
243    /**
244     * Instructs Telecom to swap the child calls of the specified conference call.
245     */
246    public void swapConference(String callId) {
247        try {
248            mAdapter.swapConference(callId);
249        } catch (RemoteException ignored) {
250        }
251    }
252
253    /**
254     * Instructs Telecom to turn the proximity sensor on.
255     */
256    public void turnProximitySensorOn() {
257        try {
258            mAdapter.turnOnProximitySensor();
259        } catch (RemoteException ignored) {
260        }
261    }
262
263    /**
264     * Instructs Telecom to turn the proximity sensor off.
265     *
266     * @param screenOnImmediately If true, the screen will be turned on immediately if it was
267     * previously off. Otherwise, the screen will only be turned on after the proximity sensor
268     * is no longer triggered.
269     */
270    public void turnProximitySensorOff(boolean screenOnImmediately) {
271        try {
272            mAdapter.turnOffProximitySensor(screenOnImmediately);
273        } catch (RemoteException ignored) {
274        }
275    }
276}
277