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 
17 package android.telecom;
18 
19 import android.os.RemoteException;
20 
21 import 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  */
36 public final class InCallAdapter {
37     private final IInCallAdapter mAdapter;
38 
39     /**
40      * {@hide}
41      */
InCallAdapter(IInCallAdapter adapter)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      */
answerCall(String callId, int videoState)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      */
rejectCall(String callId, boolean rejectWithMessage, String textMessage)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      */
disconnectCall(String callId)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      */
holdCall(String callId)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      */
unholdCall(String callId)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      */
mute(boolean shouldMute)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      */
setAudioRoute(int route)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      */
playDtmfTone(String callId, char digit)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      */
stopDtmfTone(String callId)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      */
postDialContinue(String callId, boolean proceed)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      */
phoneAccountSelected(String callId, PhoneAccountHandle accountHandle, boolean setDefault)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      */
conference(String callId, String otherCallId)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      */
splitFromConference(String callId)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      */
mergeConference(String callId)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      */
swapConference(String callId)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      */
turnProximitySensorOn()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      */
turnProximitySensorOff(boolean screenOnImmediately)270     public void turnProximitySensorOff(boolean screenOnImmediately) {
271         try {
272             mAdapter.turnOffProximitySensor(screenOnImmediately);
273         } catch (RemoteException ignored) {
274         }
275     }
276 }
277