blob: 2a5ddfd891b1e1d7bfd24c06d7d70d93dc3019fc [file] [log] [blame]
Ihab Awade63fadb2014-07-09 21:52:04 -07001/*
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
Tyler Gunnef9f6f92014-09-12 22:16:17 -070017package android.telecom;
Ihab Awade63fadb2014-07-09 21:52:04 -070018
Hall Liu95d55872017-01-25 17:12:49 -080019import android.annotation.IntDef;
Ravi Paluri404babb2020-01-23 19:02:44 +053020import android.annotation.NonNull;
Hall Liu95d55872017-01-25 17:12:49 -080021import android.annotation.Nullable;
Andrew Leeda80c872015-04-15 14:09:50 -070022import android.annotation.SystemApi;
Hall Liu6dfa2492019-10-01 17:20:39 -070023import android.annotation.TestApi;
Artur Satayev53ada2a2019-12-10 17:47:56 +000024import android.compat.annotation.UnsupportedAppUsage;
Tyler Gunn460b7d42020-05-15 10:19:32 -070025import android.content.pm.ServiceInfo;
Ihab Awade63fadb2014-07-09 21:52:04 -070026import android.net.Uri;
Tyler Gunn6e3ecc42018-11-12 11:30:56 -080027import android.os.Build;
Nancy Chen10798dc2014-08-08 14:00:25 -070028import android.os.Bundle;
Andrew Lee011728f2015-04-23 15:47:06 -070029import android.os.Handler;
Hall Liu95d55872017-01-25 17:12:49 -080030import android.os.ParcelFileDescriptor;
Ihab Awade63fadb2014-07-09 21:52:04 -070031
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -080032import com.android.internal.telecom.IVideoProvider;
33
Hall Liu95d55872017-01-25 17:12:49 -080034import java.io.IOException;
35import java.io.InputStreamReader;
36import java.io.OutputStreamWriter;
Hall Liu95d55872017-01-25 17:12:49 -080037import java.lang.annotation.Retention;
38import java.lang.annotation.RetentionPolicy;
39import java.nio.charset.StandardCharsets;
Ihab Awade63fadb2014-07-09 21:52:04 -070040import java.util.ArrayList;
Tyler Gunn071be6f2016-05-10 14:52:33 -070041import java.util.Arrays;
Ihab Awade63fadb2014-07-09 21:52:04 -070042import java.util.Collections;
43import java.util.List;
Santos Cordon7c7bc7f2014-07-28 18:15:48 -070044import java.util.Map;
Ihab Awade63fadb2014-07-09 21:52:04 -070045import java.util.Objects;
Jay Shrauner229e3822014-08-15 09:23:07 -070046import java.util.concurrent.CopyOnWriteArrayList;
Ihab Awade63fadb2014-07-09 21:52:04 -070047
48/**
49 * Represents an ongoing phone call that the in-call app should present to the user.
50 */
51public final class Call {
52 /**
53 * The state of a {@code Call} when newly created.
54 */
55 public static final int STATE_NEW = 0;
56
57 /**
58 * The state of an outgoing {@code Call} when dialing the remote number, but not yet connected.
59 */
60 public static final int STATE_DIALING = 1;
61
62 /**
63 * The state of an incoming {@code Call} when ringing locally, but not yet connected.
64 */
65 public static final int STATE_RINGING = 2;
66
67 /**
68 * The state of a {@code Call} when in a holding state.
69 */
70 public static final int STATE_HOLDING = 3;
71
72 /**
73 * The state of a {@code Call} when actively supporting conversation.
74 */
75 public static final int STATE_ACTIVE = 4;
76
77 /**
78 * The state of a {@code Call} when no further voice or other communication is being
79 * transmitted, the remote side has been or will inevitably be informed that the {@code Call}
80 * is no longer active, and the local data transport has or inevitably will release resources
81 * associated with this {@code Call}.
82 */
83 public static final int STATE_DISCONNECTED = 7;
84
Nancy Chen5da0fd52014-07-08 14:16:17 -070085 /**
Santos Cordone3c507b2015-04-23 14:44:19 -070086 * The state of an outgoing {@code Call} when waiting on user to select a
87 * {@link PhoneAccount} through which to place the call.
Nancy Chen5da0fd52014-07-08 14:16:17 -070088 */
Santos Cordone3c507b2015-04-23 14:44:19 -070089 public static final int STATE_SELECT_PHONE_ACCOUNT = 8;
90
91 /**
92 * @hide
93 * @deprecated use STATE_SELECT_PHONE_ACCOUNT.
94 */
95 @Deprecated
96 @SystemApi
97 public static final int STATE_PRE_DIAL_WAIT = STATE_SELECT_PHONE_ACCOUNT;
Nancy Chen5da0fd52014-07-08 14:16:17 -070098
Nancy Chene20930f2014-08-07 16:17:21 -070099 /**
Nancy Chene9b7a8e2014-08-08 14:26:27 -0700100 * The initial state of an outgoing {@code Call}.
101 * Common transitions are to {@link #STATE_DIALING} state for a successful call or
102 * {@link #STATE_DISCONNECTED} if it failed.
Nancy Chene20930f2014-08-07 16:17:21 -0700103 */
104 public static final int STATE_CONNECTING = 9;
105
Nancy Chen513c8922014-09-17 14:47:20 -0700106 /**
Tyler Gunn4afc6af2014-10-07 10:14:55 -0700107 * The state of a {@code Call} when the user has initiated a disconnection of the call, but the
108 * call has not yet been disconnected by the underlying {@code ConnectionService}. The next
109 * state of the call is (potentially) {@link #STATE_DISCONNECTED}.
110 */
111 public static final int STATE_DISCONNECTING = 10;
112
113 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700114 * The state of an external call which is in the process of being pulled from a remote device to
115 * the local device.
116 * <p>
117 * A call can only be in this state if the {@link Details#PROPERTY_IS_EXTERNAL_CALL} property
118 * and {@link Details#CAPABILITY_CAN_PULL_CALL} capability are set on the call.
119 * <p>
120 * An {@link InCallService} will only see this state if it has the
121 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true} in its
122 * manifest.
123 */
124 public static final int STATE_PULLING_CALL = 11;
125
126 /**
Hall Liu6dfa2492019-10-01 17:20:39 -0700127 * The state of a call that is active with the network, but the audio from the call is
128 * being intercepted by an app on the local device. Telecom does not hold audio focus in this
129 * state, and the call will be invisible to the user except for a persistent notification.
130 */
131 public static final int STATE_AUDIO_PROCESSING = 12;
132
133 /**
134 * The state of a call that is being presented to the user after being in
135 * {@link #STATE_AUDIO_PROCESSING}. The call is still active with the network in this case, and
136 * Telecom will hold audio focus and play a ringtone if appropriate.
137 */
138 public static final int STATE_SIMULATED_RINGING = 13;
139
140 /**
Nancy Chen513c8922014-09-17 14:47:20 -0700141 * The key to retrieve the optional {@code PhoneAccount}s Telecom can bundle with its Call
142 * extras. Used to pass the phone accounts to display on the front end to the user in order to
143 * select phone accounts to (for example) place a call.
Hall Liu34d9e242018-11-21 17:05:58 -0800144 * @deprecated Use the list from {@link #EXTRA_SUGGESTED_PHONE_ACCOUNTS} instead.
Nancy Chen513c8922014-09-17 14:47:20 -0700145 */
Hall Liu34d9e242018-11-21 17:05:58 -0800146 @Deprecated
Nancy Chen513c8922014-09-17 14:47:20 -0700147 public static final String AVAILABLE_PHONE_ACCOUNTS = "selectPhoneAccountAccounts";
148
mike dooley4af561f2016-12-20 08:55:17 -0800149 /**
Hall Liu34d9e242018-11-21 17:05:58 -0800150 * Key for extra used to pass along a list of {@link PhoneAccountSuggestion}s to the in-call
151 * UI when a call enters the {@link #STATE_SELECT_PHONE_ACCOUNT} state. The list included here
152 * will have the same length and be in the same order as the list passed with
153 * {@link #AVAILABLE_PHONE_ACCOUNTS}.
154 */
155 public static final String EXTRA_SUGGESTED_PHONE_ACCOUNTS =
156 "android.telecom.extra.SUGGESTED_PHONE_ACCOUNTS";
157
158 /**
mike dooley91217422017-03-09 12:58:42 -0800159 * Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC)
160 * when the last outgoing emergency call was made. This is used to identify potential emergency
161 * callbacks.
mike dooley4af561f2016-12-20 08:55:17 -0800162 */
163 public static final String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS =
164 "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS";
165
Usman Abdullahb0dc29a2019-03-06 15:54:56 -0800166
167 /**
168 * Extra key used to indicate whether a {@link CallScreeningService} has requested to silence
169 * the ringtone for a call. If the {@link InCallService} declares
170 * {@link TelecomManager#METADATA_IN_CALL_SERVICE_RINGING} in its manifest, it should not
171 * play a ringtone for an incoming call with this extra key set.
172 */
173 public static final String EXTRA_SILENT_RINGING_REQUESTED =
174 "android.telecom.extra.SILENT_RINGING_REQUESTED";
175
Tyler Gunn8bf76572017-04-06 15:30:08 -0700176 /**
177 * Call event sent from a {@link Call} via {@link #sendCallEvent(String, Bundle)} to inform
178 * Telecom that the user has requested that the current {@link Call} should be handed over
179 * to another {@link ConnectionService}.
180 * <p>
181 * The caller must specify the {@link #EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE} to indicate to
182 * Telecom which {@link PhoneAccountHandle} the {@link Call} should be handed over to.
183 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700184 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
185 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700186 */
187 public static final String EVENT_REQUEST_HANDOVER =
188 "android.telecom.event.REQUEST_HANDOVER";
189
190 /**
191 * Extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Specifies the
192 * {@link PhoneAccountHandle} to which a call should be handed over to.
193 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700194 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
195 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700196 */
197 public static final String EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE =
198 "android.telecom.extra.HANDOVER_PHONE_ACCOUNT_HANDLE";
199
200 /**
201 * Integer extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Specifies the
202 * video state of the call when it is handed over to the new {@link PhoneAccount}.
203 * <p>
204 * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
205 * {@link VideoProfile#STATE_BIDIRECTIONAL}, {@link VideoProfile#STATE_RX_ENABLED}, and
206 * {@link VideoProfile#STATE_TX_ENABLED}.
207 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700208 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
209 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700210 */
211 public static final String EXTRA_HANDOVER_VIDEO_STATE =
212 "android.telecom.extra.HANDOVER_VIDEO_STATE";
213
214 /**
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700215 * Extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Used by the
216 * {@link InCallService} initiating a handover to provide a {@link Bundle} with extra
217 * information to the handover {@link ConnectionService} specified by
218 * {@link #EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE}.
219 * <p>
220 * This {@link Bundle} is not interpreted by Telecom, but passed as-is to the
221 * {@link ConnectionService} via the request extras when
222 * {@link ConnectionService#onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}
223 * is called to initate the handover.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700224 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700225 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
226 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700227 */
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700228 public static final String EXTRA_HANDOVER_EXTRAS = "android.telecom.extra.HANDOVER_EXTRAS";
Tyler Gunn8bf76572017-04-06 15:30:08 -0700229
230 /**
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700231 * Call event sent from Telecom to the handover {@link ConnectionService} via
232 * {@link Connection#onCallEvent(String, Bundle)} to inform a {@link Connection} that a handover
233 * to the {@link ConnectionService} has completed successfully.
234 * <p>
235 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700236 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700237 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
238 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700239 */
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700240 public static final String EVENT_HANDOVER_COMPLETE =
241 "android.telecom.event.HANDOVER_COMPLETE";
Tyler Gunn34a2b312017-06-23 08:32:00 -0700242
243 /**
244 * Call event sent from Telecom to the handover destination {@link ConnectionService} via
245 * {@link Connection#onCallEvent(String, Bundle)} to inform the handover destination that the
246 * source connection has disconnected. The {@link Bundle} parameter for the call event will be
247 * {@code null}.
248 * <p>
249 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
250 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700251 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
252 * APIs instead.
Tyler Gunn34a2b312017-06-23 08:32:00 -0700253 */
254 public static final String EVENT_HANDOVER_SOURCE_DISCONNECTED =
255 "android.telecom.event.HANDOVER_SOURCE_DISCONNECTED";
256
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700257 /**
258 * Call event sent from Telecom to the handover {@link ConnectionService} via
259 * {@link Connection#onCallEvent(String, Bundle)} to inform a {@link Connection} that a handover
260 * to the {@link ConnectionService} has failed.
261 * <p>
262 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
263 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700264 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
265 * APIs instead.
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700266 */
267 public static final String EVENT_HANDOVER_FAILED =
268 "android.telecom.event.HANDOVER_FAILED";
Tyler Gunn8bf76572017-04-06 15:30:08 -0700269
Tyler Gunnd5821842021-02-05 11:12:57 -0800270 /**
271 * Event reported from the Telecom stack to report an in-call diagnostic message which the
272 * dialer app may opt to display to the user. A diagnostic message is used to communicate
273 * scenarios the device has detected which may impact the quality of the ongoing call.
274 * <p>
275 * For example a problem with a bluetooth headset may generate a recommendation for the user to
276 * try using the speakerphone instead, or if the device detects it has entered a poor service
277 * area, the user might be warned so that they can finish their call prior to it dropping.
278 * <p>
279 * A diagnostic message is considered persistent in nature. When the user enters a poor service
280 * area, for example, the accompanying diagnostic message persists until they leave the area
281 * of poor service. Each message is accompanied with a {@link #EXTRA_DIAGNOSTIC_MESSAGE_ID}
282 * which uniquely identifies the diagnostic condition being reported. The framework raises a
283 * call event of type {@link #EVENT_CLEAR_DIAGNOSTIC_MESSAGE} when the condition reported has
284 * been cleared. The dialer app should display the diagnostic message until it is cleared.
285 * If multiple diagnostic messages are sent with different IDs (which have not yet been cleared)
286 * the dialer app should prioritize the most recently received message, but still provide the
287 * user with a means to review past messages.
288 * <p>
289 * The text of the message is found in {@link #EXTRA_DIAGNOSTIC_MESSAGE} in the form of a human
290 * readable {@link CharSequence} which is intended for display in the call UX.
291 * <p>
292 * The telecom framework audibly notifies the user of the presence of a diagnostic message, so
293 * the dialer app needs only to concern itself with visually displaying the message.
294 * <p>
295 * The dialer app receives this event via
296 * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
297 */
298 public static final String EVENT_DISPLAY_DIAGNOSTIC_MESSAGE =
299 "android.telecom.event.DISPLAY_DIAGNOSTIC_MESSAGE";
300
301 /**
302 * Event reported from the telecom framework when a diagnostic message previously raised with
303 * {@link #EVENT_DISPLAY_DIAGNOSTIC_MESSAGE} has cleared and is no longer pertinent.
304 * <p>
305 * The {@link #EXTRA_DIAGNOSTIC_MESSAGE_ID} indicates the diagnostic message which has been
306 * cleared.
307 * <p>
308 * The dialer app receives this event via
309 * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
310 */
311 public static final String EVENT_CLEAR_DIAGNOSTIC_MESSAGE =
312 "android.telecom.event.CLEAR_DIAGNOSTIC_MESSAGE";
313
314 /**
315 * Integer extra representing a message ID for a message posted via
316 * {@link #EVENT_DISPLAY_DIAGNOSTIC_MESSAGE}. Used to ensure that the dialer app knows when
317 * the message in question has cleared via {@link #EVENT_CLEAR_DIAGNOSTIC_MESSAGE}.
318 */
319 public static final String EXTRA_DIAGNOSTIC_MESSAGE_ID =
320 "android.telecom.extra.DIAGNOSTIC_MESSAGE_ID";
321
322 /**
323 * {@link CharSequence} extra used with {@link #EVENT_DISPLAY_DIAGNOSTIC_MESSAGE}. This is the
324 * diagnostic message the dialer app should display.
325 */
326 public static final String EXTRA_DIAGNOSTIC_MESSAGE =
327 "android.telecom.extra.DIAGNOSTIC_MESSAGE";
Tyler Gunnfacfdee2020-01-23 13:10:37 -0800328
329 /**
330 * Reject reason used with {@link #reject(int)} to indicate that the user is rejecting this
331 * call because they have declined to answer it. This typically means that they are unable
332 * to answer the call at this time and would prefer it be sent to voicemail.
333 */
334 public static final int REJECT_REASON_DECLINED = 1;
335
336 /**
337 * Reject reason used with {@link #reject(int)} to indicate that the user is rejecting this
338 * call because it is an unwanted call. This allows the user to indicate that they are
339 * rejecting a call because it is likely a nuisance call.
340 */
341 public static final int REJECT_REASON_UNWANTED = 2;
342
343 /**
344 * @hide
345 */
346 @IntDef(prefix = { "REJECT_REASON_" },
347 value = {REJECT_REASON_DECLINED, REJECT_REASON_UNWANTED})
348 @Retention(RetentionPolicy.SOURCE)
349 public @interface RejectReason {};
350
Ihab Awade63fadb2014-07-09 21:52:04 -0700351 public static class Details {
Tyler Gunn94f8f112018-12-17 09:56:11 -0800352 /** @hide */
353 @Retention(RetentionPolicy.SOURCE)
354 @IntDef(
355 prefix = { "DIRECTION_" },
356 value = {DIRECTION_UNKNOWN, DIRECTION_INCOMING, DIRECTION_OUTGOING})
357 public @interface CallDirection {}
358
359 /**
360 * Indicates that the call is neither and incoming nor an outgoing call. This can be the
361 * case for calls reported directly by a {@link ConnectionService} in special cases such as
362 * call handovers.
363 */
364 public static final int DIRECTION_UNKNOWN = -1;
365
366 /**
367 * Indicates that the call is an incoming call.
368 */
369 public static final int DIRECTION_INCOMING = 0;
370
371 /**
372 * Indicates that the call is an outgoing call.
373 */
374 public static final int DIRECTION_OUTGOING = 1;
375
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800376 /** Call can currently be put on hold or unheld. */
377 public static final int CAPABILITY_HOLD = 0x00000001;
378
379 /** Call supports the hold feature. */
380 public static final int CAPABILITY_SUPPORT_HOLD = 0x00000002;
381
382 /**
383 * Calls within a conference can be merged. A {@link ConnectionService} has the option to
384 * add a {@link Conference} call before the child {@link Connection}s are merged. This is how
385 * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this
386 * capability allows a merge button to be shown while the conference call is in the foreground
387 * of the in-call UI.
388 * <p>
389 * This is only intended for use by a {@link Conference}.
390 */
391 public static final int CAPABILITY_MERGE_CONFERENCE = 0x00000004;
392
393 /**
394 * Calls within a conference can be swapped between foreground and background.
395 * See {@link #CAPABILITY_MERGE_CONFERENCE} for additional information.
396 * <p>
397 * This is only intended for use by a {@link Conference}.
398 */
399 public static final int CAPABILITY_SWAP_CONFERENCE = 0x00000008;
400
401 /**
402 * @hide
403 */
Andrew Lee2378ea72015-04-29 14:38:11 -0700404 public static final int CAPABILITY_UNUSED_1 = 0x00000010;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800405
406 /** Call supports responding via text option. */
407 public static final int CAPABILITY_RESPOND_VIA_TEXT = 0x00000020;
408
409 /** Call can be muted. */
410 public static final int CAPABILITY_MUTE = 0x00000040;
411
412 /**
413 * Call supports conference call management. This capability only applies to {@link Conference}
414 * calls which can have {@link Connection}s as children.
415 */
416 public static final int CAPABILITY_MANAGE_CONFERENCE = 0x00000080;
417
418 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700419 * Local device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800420 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700421 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_RX = 0x00000100;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800422
423 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700424 * Local device supports transmitting video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800425 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700426 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_TX = 0x00000200;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800427
428 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700429 * Local device supports bidirectional video calling.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800430 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700431 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700432 CAPABILITY_SUPPORTS_VT_LOCAL_RX | CAPABILITY_SUPPORTS_VT_LOCAL_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800433
434 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700435 * Remote device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800436 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700437 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_RX = 0x00000400;
438
439 /**
440 * Remote device supports transmitting video.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700441 */
442 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_TX = 0x00000800;
443
444 /**
445 * Remote device supports bidirectional video calling.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700446 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700447 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700448 CAPABILITY_SUPPORTS_VT_REMOTE_RX | CAPABILITY_SUPPORTS_VT_REMOTE_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800449
450 /**
451 * Call is able to be separated from its parent {@code Conference}, if any.
452 */
453 public static final int CAPABILITY_SEPARATE_FROM_CONFERENCE = 0x00001000;
454
455 /**
456 * Call is able to be individually disconnected when in a {@code Conference}.
457 */
458 public static final int CAPABILITY_DISCONNECT_FROM_CONFERENCE = 0x00002000;
459
460 /**
Dong Zhou89f41eb2015-03-15 11:59:49 -0500461 * Speed up audio setup for MT call.
462 * @hide
463 */
Tyler Gunn96d6c402015-03-18 12:39:23 -0700464 public static final int CAPABILITY_SPEED_UP_MT_AUDIO = 0x00040000;
465
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700466 /**
467 * Call can be upgraded to a video call.
Rekha Kumar07366812015-03-24 16:42:31 -0700468 * @hide
Tyler Gunn6e3ecc42018-11-12 11:30:56 -0800469 * @deprecated Use {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
470 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL} to indicate for a call
471 * whether or not video calling is supported.
Rekha Kumar07366812015-03-24 16:42:31 -0700472 */
Tyler Gunn6e3ecc42018-11-12 11:30:56 -0800473 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 119305590)
Rekha Kumar07366812015-03-24 16:42:31 -0700474 public static final int CAPABILITY_CAN_UPGRADE_TO_VIDEO = 0x00080000;
475
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700476 /**
477 * For video calls, indicates whether the outgoing video for the call can be paused using
Yorke Lee32f24732015-05-12 16:18:03 -0700478 * the {@link android.telecom.VideoProfile#STATE_PAUSED} VideoState.
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700479 */
480 public static final int CAPABILITY_CAN_PAUSE_VIDEO = 0x00100000;
481
Bryce Lee81901682015-08-28 16:38:02 -0700482 /**
483 * Call sends responses through connection.
484 * @hide
485 */
Tyler Gunnf97a0092016-01-19 15:59:34 -0800486 public static final int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION = 0x00200000;
487
488 /**
489 * When set, prevents a video {@code Call} from being downgraded to an audio-only call.
490 * <p>
491 * Should be set when the VideoState has the {@link VideoProfile#STATE_TX_ENABLED} or
492 * {@link VideoProfile#STATE_RX_ENABLED} bits set to indicate that the connection cannot be
493 * downgraded from a video call back to a VideoState of
494 * {@link VideoProfile#STATE_AUDIO_ONLY}.
495 * <p>
496 * Intuitively, a call which can be downgraded to audio should also have local and remote
497 * video
498 * capabilities (see {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
499 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL}).
500 */
501 public static final int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO = 0x00400000;
Bryce Lee81901682015-08-28 16:38:02 -0700502
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700503 /**
504 * When set for an external call, indicates that this {@code Call} can be pulled from a
505 * remote device to the current device.
506 * <p>
507 * Should only be set on a {@code Call} where {@link #PROPERTY_IS_EXTERNAL_CALL} is set.
508 * <p>
509 * An {@link InCallService} will only see calls with this capability if it has the
510 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
511 * in its manifest.
512 * <p>
513 * See {@link Connection#CAPABILITY_CAN_PULL_CALL} and
Tyler Gunn720c6642016-03-22 09:02:47 -0700514 * {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700515 */
516 public static final int CAPABILITY_CAN_PULL_CALL = 0x00800000;
517
Pooja Jaind34698d2017-12-28 14:15:31 +0530518 /** Call supports the deflect feature. */
519 public static final int CAPABILITY_SUPPORT_DEFLECT = 0x01000000;
520
Tyler Gunn0c62ef02020-02-11 14:39:43 -0800521 /**
522 * Call supports adding participants to the call via
Grace Jia8587ee52020-07-10 15:42:32 -0700523 * {@link #addConferenceParticipants(List)}. Once participants are added, the call becomes
524 * an adhoc conference call ({@link #PROPERTY_IS_ADHOC_CONFERENCE}).
Tyler Gunn0c62ef02020-02-11 14:39:43 -0800525 */
Ravi Paluri404babb2020-01-23 19:02:44 +0530526 public static final int CAPABILITY_ADD_PARTICIPANT = 0x02000000;
Ravi Palurif4b38e72020-02-05 12:35:41 +0530527
528 /**
529 * When set for a call, indicates that this {@code Call} can be transferred to another
530 * number.
Tyler Gunn460360d2020-07-29 10:21:45 -0700531 * Call supports the confirmed and unconfirmed call transfer feature.
Ravi Palurif4b38e72020-02-05 12:35:41 +0530532 *
533 * @hide
534 */
535 public static final int CAPABILITY_TRANSFER = 0x04000000;
536
537 /**
538 * When set for a call, indicates that this {@code Call} can be transferred to another
539 * ongoing call.
540 * Call supports the consultative call transfer feature.
541 *
542 * @hide
543 */
544 public static final int CAPABILITY_TRANSFER_CONSULTATIVE = 0x08000000;
545
Tyler Gunnd11a3152015-03-18 13:09:14 -0700546 //******************************************************************************************
Ravi Palurif4b38e72020-02-05 12:35:41 +0530547 // Next CAPABILITY value: 0x10000000
Andrew Lee2378ea72015-04-29 14:38:11 -0700548 //******************************************************************************************
549
550 /**
551 * Whether the call is currently a conference.
552 */
553 public static final int PROPERTY_CONFERENCE = 0x00000001;
554
555 /**
556 * Whether the call is a generic conference, where we do not know the precise state of
557 * participants in the conference (eg. on CDMA).
558 */
559 public static final int PROPERTY_GENERIC_CONFERENCE = 0x00000002;
560
561 /**
562 * Whether the call is made while the device is in emergency callback mode.
563 */
564 public static final int PROPERTY_EMERGENCY_CALLBACK_MODE = 0x00000004;
565
566 /**
567 * Connection is using WIFI.
568 */
569 public static final int PROPERTY_WIFI = 0x00000008;
570
571 /**
Tyler Gunn6b6ae552018-10-11 10:42:10 -0700572 * When set, the UI should indicate to the user that a call is using high definition
573 * audio.
574 * <p>
575 * The underlying {@link ConnectionService} is responsible for reporting this
576 * property. It is important to note that this property is not intended to report the
577 * actual audio codec being used for a Call, but whether the call should be indicated
578 * to the user as high definition.
579 * <p>
580 * The Android Telephony stack reports this property for calls based on a number
581 * of factors, including which audio codec is used and whether a call is using an HD
582 * codec end-to-end. Some mobile operators choose to suppress display of an HD indication,
583 * and in these cases this property will not be set for a call even if the underlying audio
584 * codec is in fact "high definition".
Andrew Lee2378ea72015-04-29 14:38:11 -0700585 */
586 public static final int PROPERTY_HIGH_DEF_AUDIO = 0x00000010;
587
Tony Maka68dcce2015-12-17 09:31:18 +0000588 /**
Tony Mak53b5df42016-05-19 13:40:38 +0100589 * Whether the call is associated with the work profile.
590 */
591 public static final int PROPERTY_ENTERPRISE_CALL = 0x00000020;
592
593 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700594 * When set, indicates that this {@code Call} does not actually exist locally for the
595 * {@link ConnectionService}.
596 * <p>
597 * Consider, for example, a scenario where a user has two phones with the same phone number.
598 * When a user places a call on one device, the telephony stack can represent that call on
599 * the other device by adding it to the {@link ConnectionService} with the
Tyler Gunn720c6642016-03-22 09:02:47 -0700600 * {@link Connection#PROPERTY_IS_EXTERNAL_CALL} property set.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700601 * <p>
602 * An {@link InCallService} will only see calls with this property if it has the
603 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
604 * in its manifest.
605 * <p>
Tyler Gunn720c6642016-03-22 09:02:47 -0700606 * See {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700607 */
608 public static final int PROPERTY_IS_EXTERNAL_CALL = 0x00000040;
609
Brad Ebinger15847072016-05-18 11:08:36 -0700610 /**
611 * Indicates that the call has CDMA Enhanced Voice Privacy enabled.
612 */
613 public static final int PROPERTY_HAS_CDMA_VOICE_PRIVACY = 0x00000080;
614
Tyler Gunn24e18332017-02-10 09:42:49 -0800615 /**
616 * Indicates that the call is from a self-managed {@link ConnectionService}.
617 * <p>
618 * See also {@link Connection#PROPERTY_SELF_MANAGED}
619 */
620 public static final int PROPERTY_SELF_MANAGED = 0x00000100;
621
Eric Erfanianec881872017-12-06 16:27:53 -0800622 /**
623 * Indicates the call used Assisted Dialing.
Tyler Gunn5567d742019-10-31 13:04:37 -0700624 *
625 * @see TelecomManager#EXTRA_USE_ASSISTED_DIALING
Eric Erfanianec881872017-12-06 16:27:53 -0800626 */
Tyler Gunnc9503d62020-01-27 10:30:51 -0800627 public static final int PROPERTY_ASSISTED_DIALING = 0x00000200;
Eric Erfanianec881872017-12-06 16:27:53 -0800628
Hall Liue9041242018-02-09 16:40:03 -0800629 /**
630 * Indicates that the call is an RTT call. Use {@link #getRttCall()} to get the
631 * {@link RttCall} object that is used to send and receive text.
632 */
633 public static final int PROPERTY_RTT = 0x00000400;
634
Tyler Gunn5bd90852018-09-21 09:37:07 -0700635 /**
636 * Indicates that the call has been identified as the network as an emergency call. This
637 * property may be set for both incoming and outgoing calls which the network identifies as
638 * emergency calls.
639 */
640 public static final int PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL = 0x00000800;
641
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700642 /**
643 * Indicates that the call is using VoIP audio mode.
644 * <p>
645 * When this property is set, the {@link android.media.AudioManager} audio mode for this
646 * call will be {@link android.media.AudioManager#MODE_IN_COMMUNICATION}. When this
647 * property is not set, the audio mode for this call will be
648 * {@link android.media.AudioManager#MODE_IN_CALL}.
649 * <p>
650 * This property reflects changes made using {@link Connection#setAudioModeIsVoip(boolean)}.
651 * <p>
652 * You can use this property to determine whether an un-answered incoming call or a held
653 * call will use VoIP audio mode (if the call does not currently have focus, the system
654 * audio mode may not reflect the mode the call will use).
655 */
656 public static final int PROPERTY_VOIP_AUDIO_MODE = 0x00001000;
657
Ravi Paluri80aa2142019-12-02 11:57:37 +0530658 /**
659 * Indicates that the call is an adhoc conference call. This property can be set for both
Grace Jia8587ee52020-07-10 15:42:32 -0700660 * incoming and outgoing calls. An adhoc conference call is formed using
661 * {@link #addConferenceParticipants(List)},
662 * {@link TelecomManager#addNewIncomingConference(PhoneAccountHandle, Bundle)}, or
663 * {@link TelecomManager#startConference(List, Bundle)}, rather than by merging existing
664 * call using {@link #conference(Call)}.
Ravi Paluri80aa2142019-12-02 11:57:37 +0530665 */
666 public static final int PROPERTY_IS_ADHOC_CONFERENCE = 0x00002000;
667
Sooraj Sasindran64f05b12020-11-18 12:07:10 -0800668 /**
669 * Connection is using Cross SIM Calling.
670 */
671 public static final int PROPERTY_CROSS_SIM = 0x00004000;
672
Andrew Lee2378ea72015-04-29 14:38:11 -0700673 //******************************************************************************************
Ravi Paluri80aa2142019-12-02 11:57:37 +0530674 // Next PROPERTY value: 0x00004000
Tyler Gunnd11a3152015-03-18 13:09:14 -0700675 //******************************************************************************************
Tyler Gunn068085b2015-02-06 13:56:52 -0800676
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800677 private final String mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -0700678 private final Uri mHandle;
679 private final int mHandlePresentation;
680 private final String mCallerDisplayName;
681 private final int mCallerDisplayNamePresentation;
Evan Charlton8c8a0622014-07-20 12:31:00 -0700682 private final PhoneAccountHandle mAccountHandle;
Ihab Awad5d0410f2014-07-30 10:07:40 -0700683 private final int mCallCapabilities;
Andrew Lee223ad142014-08-27 16:33:08 -0700684 private final int mCallProperties;
Christine Hallstrom4e22d6d2016-11-30 16:06:42 -0800685 private final int mSupportedAudioRoutes = CallAudioState.ROUTE_ALL;
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700686 private final DisconnectCause mDisconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -0700687 private final long mConnectTimeMillis;
688 private final GatewayInfo mGatewayInfo;
Andrew Lee85f5d422014-07-11 17:22:03 -0700689 private final int mVideoState;
Evan Charlton5b49ade2014-07-15 17:03:20 -0700690 private final StatusHints mStatusHints;
Nancy Chen10798dc2014-08-08 14:00:25 -0700691 private final Bundle mExtras;
Santos Cordon6b7f9552015-05-27 17:21:45 -0700692 private final Bundle mIntentExtras;
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700693 private final long mCreationTimeMillis;
Hall Liuef98bf82020-01-09 15:22:44 -0800694 private final String mContactDisplayName;
Tyler Gunn94f8f112018-12-17 09:56:11 -0800695 private final @CallDirection int mCallDirection;
Tyler Gunnd57d76c2019-09-24 14:53:23 -0700696 private final @Connection.VerificationStatus int mCallerNumberVerificationStatus;
Ihab Awade63fadb2014-07-09 21:52:04 -0700697
698 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800699 * Whether the supplied capabilities supports the specified capability.
700 *
701 * @param capabilities A bit field of capabilities.
702 * @param capability The capability to check capabilities for.
703 * @return Whether the specified capability is supported.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800704 */
705 public static boolean can(int capabilities, int capability) {
Tyler Gunn014c7112015-12-18 14:33:57 -0800706 return (capabilities & capability) == capability;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800707 }
708
709 /**
710 * Whether the capabilities of this {@code Details} supports the specified capability.
711 *
712 * @param capability The capability to check capabilities for.
713 * @return Whether the specified capability is supported.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800714 */
715 public boolean can(int capability) {
716 return can(mCallCapabilities, capability);
717 }
718
719 /**
720 * Render a set of capability bits ({@code CAPABILITY_*}) as a human readable string.
721 *
722 * @param capabilities A capability bit field.
723 * @return A human readable string representation.
724 */
725 public static String capabilitiesToString(int capabilities) {
726 StringBuilder builder = new StringBuilder();
727 builder.append("[Capabilities:");
728 if (can(capabilities, CAPABILITY_HOLD)) {
729 builder.append(" CAPABILITY_HOLD");
730 }
731 if (can(capabilities, CAPABILITY_SUPPORT_HOLD)) {
732 builder.append(" CAPABILITY_SUPPORT_HOLD");
733 }
734 if (can(capabilities, CAPABILITY_MERGE_CONFERENCE)) {
735 builder.append(" CAPABILITY_MERGE_CONFERENCE");
736 }
737 if (can(capabilities, CAPABILITY_SWAP_CONFERENCE)) {
738 builder.append(" CAPABILITY_SWAP_CONFERENCE");
739 }
740 if (can(capabilities, CAPABILITY_RESPOND_VIA_TEXT)) {
741 builder.append(" CAPABILITY_RESPOND_VIA_TEXT");
742 }
743 if (can(capabilities, CAPABILITY_MUTE)) {
744 builder.append(" CAPABILITY_MUTE");
745 }
746 if (can(capabilities, CAPABILITY_MANAGE_CONFERENCE)) {
747 builder.append(" CAPABILITY_MANAGE_CONFERENCE");
748 }
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700749 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_RX)) {
750 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_RX");
751 }
752 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_TX)) {
753 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_TX");
754 }
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700755 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL)) {
756 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800757 }
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700758 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_RX)) {
759 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_RX");
760 }
761 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_TX)) {
762 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_TX");
763 }
Tyler Gunnf97a0092016-01-19 15:59:34 -0800764 if (can(capabilities, CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO)) {
765 builder.append(" CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO");
766 }
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700767 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL)) {
768 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800769 }
Dong Zhou89f41eb2015-03-15 11:59:49 -0500770 if (can(capabilities, CAPABILITY_SPEED_UP_MT_AUDIO)) {
Tyler Gunnd11a3152015-03-18 13:09:14 -0700771 builder.append(" CAPABILITY_SPEED_UP_MT_AUDIO");
Dong Zhou89f41eb2015-03-15 11:59:49 -0500772 }
Rekha Kumar07366812015-03-24 16:42:31 -0700773 if (can(capabilities, CAPABILITY_CAN_UPGRADE_TO_VIDEO)) {
774 builder.append(" CAPABILITY_CAN_UPGRADE_TO_VIDEO");
775 }
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700776 if (can(capabilities, CAPABILITY_CAN_PAUSE_VIDEO)) {
777 builder.append(" CAPABILITY_CAN_PAUSE_VIDEO");
778 }
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700779 if (can(capabilities, CAPABILITY_CAN_PULL_CALL)) {
780 builder.append(" CAPABILITY_CAN_PULL_CALL");
781 }
Pooja Jaind34698d2017-12-28 14:15:31 +0530782 if (can(capabilities, CAPABILITY_SUPPORT_DEFLECT)) {
783 builder.append(" CAPABILITY_SUPPORT_DEFLECT");
784 }
Ravi Paluri404babb2020-01-23 19:02:44 +0530785 if (can(capabilities, CAPABILITY_ADD_PARTICIPANT)) {
786 builder.append(" CAPABILITY_ADD_PARTICIPANT");
787 }
Ravi Palurif4b38e72020-02-05 12:35:41 +0530788 if (can(capabilities, CAPABILITY_TRANSFER)) {
789 builder.append(" CAPABILITY_TRANSFER");
790 }
791 if (can(capabilities, CAPABILITY_TRANSFER_CONSULTATIVE)) {
792 builder.append(" CAPABILITY_TRANSFER_CONSULTATIVE");
793 }
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800794 builder.append("]");
795 return builder.toString();
796 }
797
798 /**
Andrew Lee2378ea72015-04-29 14:38:11 -0700799 * Whether the supplied properties includes the specified property.
800 *
801 * @param properties A bit field of properties.
802 * @param property The property to check properties for.
803 * @return Whether the specified property is supported.
804 */
805 public static boolean hasProperty(int properties, int property) {
Tyler Gunn014c7112015-12-18 14:33:57 -0800806 return (properties & property) == property;
Andrew Lee2378ea72015-04-29 14:38:11 -0700807 }
808
809 /**
810 * Whether the properties of this {@code Details} includes the specified property.
811 *
812 * @param property The property to check properties for.
813 * @return Whether the specified property is supported.
814 */
815 public boolean hasProperty(int property) {
816 return hasProperty(mCallProperties, property);
817 }
818
819 /**
820 * Render a set of property bits ({@code PROPERTY_*}) as a human readable string.
821 *
822 * @param properties A property bit field.
823 * @return A human readable string representation.
824 */
825 public static String propertiesToString(int properties) {
826 StringBuilder builder = new StringBuilder();
827 builder.append("[Properties:");
828 if (hasProperty(properties, PROPERTY_CONFERENCE)) {
829 builder.append(" PROPERTY_CONFERENCE");
830 }
831 if (hasProperty(properties, PROPERTY_GENERIC_CONFERENCE)) {
832 builder.append(" PROPERTY_GENERIC_CONFERENCE");
833 }
834 if (hasProperty(properties, PROPERTY_WIFI)) {
835 builder.append(" PROPERTY_WIFI");
836 }
837 if (hasProperty(properties, PROPERTY_HIGH_DEF_AUDIO)) {
838 builder.append(" PROPERTY_HIGH_DEF_AUDIO");
839 }
840 if (hasProperty(properties, PROPERTY_EMERGENCY_CALLBACK_MODE)) {
Yorke Leebe2a4a22015-06-12 10:10:55 -0700841 builder.append(" PROPERTY_EMERGENCY_CALLBACK_MODE");
Andrew Lee2378ea72015-04-29 14:38:11 -0700842 }
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700843 if (hasProperty(properties, PROPERTY_IS_EXTERNAL_CALL)) {
844 builder.append(" PROPERTY_IS_EXTERNAL_CALL");
845 }
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700846 if (hasProperty(properties, PROPERTY_HAS_CDMA_VOICE_PRIVACY)) {
Brad Ebinger15847072016-05-18 11:08:36 -0700847 builder.append(" PROPERTY_HAS_CDMA_VOICE_PRIVACY");
848 }
Tyler Gunnc9503d62020-01-27 10:30:51 -0800849 if (hasProperty(properties, PROPERTY_ASSISTED_DIALING)) {
Eric Erfanianec881872017-12-06 16:27:53 -0800850 builder.append(" PROPERTY_ASSISTED_DIALING_USED");
851 }
Tyler Gunn5bd90852018-09-21 09:37:07 -0700852 if (hasProperty(properties, PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL)) {
853 builder.append(" PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL");
854 }
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700855 if (hasProperty(properties, PROPERTY_RTT)) {
856 builder.append(" PROPERTY_RTT");
857 }
858 if (hasProperty(properties, PROPERTY_VOIP_AUDIO_MODE)) {
859 builder.append(" PROPERTY_VOIP_AUDIO_MODE");
860 }
Ravi Paluri80aa2142019-12-02 11:57:37 +0530861 if (hasProperty(properties, PROPERTY_IS_ADHOC_CONFERENCE)) {
862 builder.append(" PROPERTY_IS_ADHOC_CONFERENCE");
863 }
Sooraj Sasindran64f05b12020-11-18 12:07:10 -0800864 if (hasProperty(properties, PROPERTY_CROSS_SIM)) {
865 builder.append(" PROPERTY_CROSS_SIM");
866 }
Andrew Lee2378ea72015-04-29 14:38:11 -0700867 builder.append("]");
868 return builder.toString();
869 }
870
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800871 /** {@hide} */
Hall Liu31de23d2019-10-11 15:38:29 -0700872 @TestApi
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800873 public String getTelecomCallId() {
874 return mTelecomCallId;
875 }
876
Andrew Lee2378ea72015-04-29 14:38:11 -0700877 /**
Ihab Awade63fadb2014-07-09 21:52:04 -0700878 * @return The handle (e.g., phone number) to which the {@code Call} is currently
879 * connected.
880 */
881 public Uri getHandle() {
882 return mHandle;
883 }
884
885 /**
886 * @return The presentation requirements for the handle. See
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700887 * {@link TelecomManager} for valid values.
Ihab Awade63fadb2014-07-09 21:52:04 -0700888 */
889 public int getHandlePresentation() {
890 return mHandlePresentation;
891 }
892
893 /**
Tyler Gunnd081f042018-12-04 12:56:45 -0800894 * The display name for the caller.
895 * <p>
896 * This is the name as reported by the {@link ConnectionService} associated with this call.
Tyler Gunnd081f042018-12-04 12:56:45 -0800897 *
Ihab Awade63fadb2014-07-09 21:52:04 -0700898 * @return The display name for the caller.
899 */
900 public String getCallerDisplayName() {
901 return mCallerDisplayName;
902 }
903
904 /**
905 * @return The presentation requirements for the caller display name. See
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700906 * {@link TelecomManager} for valid values.
Ihab Awade63fadb2014-07-09 21:52:04 -0700907 */
908 public int getCallerDisplayNamePresentation() {
909 return mCallerDisplayNamePresentation;
910 }
911
912 /**
Evan Charlton6eb262c2014-07-19 18:18:19 -0700913 * @return The {@code PhoneAccountHandle} whereby the {@code Call} is currently being
914 * routed.
Ihab Awade63fadb2014-07-09 21:52:04 -0700915 */
Evan Charlton8c8a0622014-07-20 12:31:00 -0700916 public PhoneAccountHandle getAccountHandle() {
917 return mAccountHandle;
Ihab Awade63fadb2014-07-09 21:52:04 -0700918 }
919
920 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800921 * @return A bitmask of the capabilities of the {@code Call}, as defined by the various
922 * {@code CAPABILITY_*} constants in this class.
Ihab Awade63fadb2014-07-09 21:52:04 -0700923 */
Ihab Awad5d0410f2014-07-30 10:07:40 -0700924 public int getCallCapabilities() {
925 return mCallCapabilities;
Ihab Awade63fadb2014-07-09 21:52:04 -0700926 }
927
928 /**
Andrew Lee2378ea72015-04-29 14:38:11 -0700929 * @return A bitmask of the properties of the {@code Call}, as defined by the various
930 * {@code PROPERTY_*} constants in this class.
Andrew Lee223ad142014-08-27 16:33:08 -0700931 */
932 public int getCallProperties() {
933 return mCallProperties;
934 }
935
936 /**
Christine Hallstrom4e22d6d2016-11-30 16:06:42 -0800937 * @return a bitmask of the audio routes available for the call.
938 *
939 * @hide
940 */
941 public int getSupportedAudioRoutes() {
942 return mSupportedAudioRoutes;
943 }
944
945 /**
Ihab Awade63fadb2014-07-09 21:52:04 -0700946 * @return For a {@link #STATE_DISCONNECTED} {@code Call}, the disconnect cause expressed
Nancy Chenf4cf77c2014-09-19 10:53:21 -0700947 * by {@link android.telecom.DisconnectCause}.
Ihab Awade63fadb2014-07-09 21:52:04 -0700948 */
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700949 public DisconnectCause getDisconnectCause() {
950 return mDisconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -0700951 }
952
953 /**
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700954 * Returns the time the {@link Call} connected (i.e. became active). This information is
955 * updated periodically, but user interfaces should not rely on this to display the "call
956 * time clock". For the time when the call was first added to Telecom, see
957 * {@link #getCreationTimeMillis()}.
958 *
959 * @return The time the {@link Call} connected in milliseconds since the epoch.
Ihab Awade63fadb2014-07-09 21:52:04 -0700960 */
Jay Shrauner164a0ac2015-04-14 18:16:10 -0700961 public final long getConnectTimeMillis() {
Ihab Awade63fadb2014-07-09 21:52:04 -0700962 return mConnectTimeMillis;
963 }
964
965 /**
966 * @return Information about any calling gateway the {@code Call} may be using.
967 */
968 public GatewayInfo getGatewayInfo() {
969 return mGatewayInfo;
970 }
971
Andrew Lee7a341382014-07-15 17:05:08 -0700972 /**
Ihab Awad5d0410f2014-07-30 10:07:40 -0700973 * @return The video state of the {@code Call}.
Andrew Lee7a341382014-07-15 17:05:08 -0700974 */
975 public int getVideoState() {
976 return mVideoState;
977 }
978
Ihab Awad5d0410f2014-07-30 10:07:40 -0700979 /**
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700980 * @return The current {@link android.telecom.StatusHints}, or {@code null} if none
Ihab Awad5d0410f2014-07-30 10:07:40 -0700981 * have been set.
Evan Charlton5b49ade2014-07-15 17:03:20 -0700982 */
983 public StatusHints getStatusHints() {
984 return mStatusHints;
985 }
986
Nancy Chen10798dc2014-08-08 14:00:25 -0700987 /**
Santos Cordon6b7f9552015-05-27 17:21:45 -0700988 * @return The extras associated with this call.
Nancy Chen10798dc2014-08-08 14:00:25 -0700989 */
990 public Bundle getExtras() {
991 return mExtras;
992 }
993
Santos Cordon6b7f9552015-05-27 17:21:45 -0700994 /**
995 * @return The extras used with the original intent to place this call.
996 */
997 public Bundle getIntentExtras() {
998 return mIntentExtras;
999 }
1000
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001001 /**
1002 * Returns the time when the call was first created and added to Telecom. This is the same
1003 * time that is logged as the start time in the Call Log (see
1004 * {@link android.provider.CallLog.Calls#DATE}). To determine when the call was connected
1005 * (became active), see {@link #getConnectTimeMillis()}.
1006 *
1007 * @return The creation time of the call, in millis since the epoch.
1008 */
1009 public long getCreationTimeMillis() {
1010 return mCreationTimeMillis;
1011 }
1012
Tyler Gunnd081f042018-12-04 12:56:45 -08001013 /**
Hall Liuef98bf82020-01-09 15:22:44 -08001014 * Returns the name of the caller on the remote end, as derived from a
1015 * {@link android.provider.ContactsContract} lookup of the call's handle.
1016 * @return The name of the caller, or {@code null} if the lookup is not yet complete, if
1017 * there's no contacts entry for the caller, or if the {@link InCallService} does
1018 * not hold the {@link android.Manifest.permission#READ_CONTACTS} permission.
1019 */
1020 public @Nullable String getContactDisplayName() {
1021 return mContactDisplayName;
1022 }
1023
1024 /**
Tyler Gunn94f8f112018-12-17 09:56:11 -08001025 * Indicates whether the call is an incoming or outgoing call.
1026 * @return The call's direction.
1027 */
1028 public @CallDirection int getCallDirection() {
1029 return mCallDirection;
1030 }
1031
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001032 /**
1033 * Gets the verification status for the phone number of an incoming call as identified in
1034 * ATIS-1000082.
Tyler Gunn9c642492020-10-08 13:37:03 -07001035 * <p>
1036 * For incoming calls, the number verification status indicates whether the device was
1037 * able to verify the authenticity of the calling number using the STIR process outlined
1038 * in ATIS-1000082. {@link Connection#VERIFICATION_STATUS_NOT_VERIFIED} indicates that
1039 * the network was not able to use STIR to verify the caller's number (i.e. nothing is
1040 * known regarding the authenticity of the number.
1041 * {@link Connection#VERIFICATION_STATUS_PASSED} indicates that the network was able to
1042 * use STIR to verify the caller's number. This indicates that the network has a high
1043 * degree of confidence that the incoming call actually originated from the indicated
1044 * number. {@link Connection#VERIFICATION_STATUS_FAILED} indicates that the network's
1045 * STIR verification did not pass. This indicates that the incoming call may not
1046 * actually be from the indicated number. This could occur if, for example, the caller
1047 * is using an impersonated phone number.
1048 * <p>
1049 * A {@link CallScreeningService} can use this information to help determine if an
1050 * incoming call is potentially an unwanted call. A verification status of
1051 * {@link Connection#VERIFICATION_STATUS_FAILED} indicates that an incoming call may not
1052 * actually be from the number indicated on the call (i.e. impersonated number) and that it
1053 * should potentially be blocked. Likewise,
1054 * {@link Connection#VERIFICATION_STATUS_PASSED} can be used as a positive signal to
1055 * help clarify that the incoming call is originating from the indicated number and it
1056 * is less likely to be an undesirable call.
1057 * <p>
1058 * An {@link InCallService} can use this information to provide a visual indicator to the
1059 * user regarding the verification status of a call and to help identify calls from
1060 * potentially impersonated numbers.
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001061 * @return the verification status.
1062 */
1063 public @Connection.VerificationStatus int getCallerNumberVerificationStatus() {
1064 return mCallerNumberVerificationStatus;
1065 }
1066
Ihab Awade63fadb2014-07-09 21:52:04 -07001067 @Override
1068 public boolean equals(Object o) {
1069 if (o instanceof Details) {
1070 Details d = (Details) o;
1071 return
1072 Objects.equals(mHandle, d.mHandle) &&
1073 Objects.equals(mHandlePresentation, d.mHandlePresentation) &&
1074 Objects.equals(mCallerDisplayName, d.mCallerDisplayName) &&
1075 Objects.equals(mCallerDisplayNamePresentation,
1076 d.mCallerDisplayNamePresentation) &&
Evan Charlton8c8a0622014-07-20 12:31:00 -07001077 Objects.equals(mAccountHandle, d.mAccountHandle) &&
Ihab Awad5d0410f2014-07-30 10:07:40 -07001078 Objects.equals(mCallCapabilities, d.mCallCapabilities) &&
Andrew Lee223ad142014-08-27 16:33:08 -07001079 Objects.equals(mCallProperties, d.mCallProperties) &&
Andrew Lee7f3d41f2014-09-11 17:33:16 -07001080 Objects.equals(mDisconnectCause, d.mDisconnectCause) &&
Ihab Awade63fadb2014-07-09 21:52:04 -07001081 Objects.equals(mConnectTimeMillis, d.mConnectTimeMillis) &&
Andrew Lee85f5d422014-07-11 17:22:03 -07001082 Objects.equals(mGatewayInfo, d.mGatewayInfo) &&
Evan Charlton5b49ade2014-07-15 17:03:20 -07001083 Objects.equals(mVideoState, d.mVideoState) &&
Nancy Chen10798dc2014-08-08 14:00:25 -07001084 Objects.equals(mStatusHints, d.mStatusHints) &&
Tyler Gunn1e9bfc62015-08-19 11:18:58 -07001085 areBundlesEqual(mExtras, d.mExtras) &&
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001086 areBundlesEqual(mIntentExtras, d.mIntentExtras) &&
Tyler Gunnd081f042018-12-04 12:56:45 -08001087 Objects.equals(mCreationTimeMillis, d.mCreationTimeMillis) &&
Hall Liuef98bf82020-01-09 15:22:44 -08001088 Objects.equals(mContactDisplayName, d.mContactDisplayName) &&
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001089 Objects.equals(mCallDirection, d.mCallDirection) &&
1090 Objects.equals(mCallerNumberVerificationStatus,
1091 d.mCallerNumberVerificationStatus);
Ihab Awade63fadb2014-07-09 21:52:04 -07001092 }
1093 return false;
1094 }
1095
1096 @Override
1097 public int hashCode() {
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001098 return Objects.hash(mHandle,
1099 mHandlePresentation,
1100 mCallerDisplayName,
1101 mCallerDisplayNamePresentation,
1102 mAccountHandle,
1103 mCallCapabilities,
1104 mCallProperties,
1105 mDisconnectCause,
1106 mConnectTimeMillis,
1107 mGatewayInfo,
1108 mVideoState,
1109 mStatusHints,
1110 mExtras,
1111 mIntentExtras,
Tyler Gunnd081f042018-12-04 12:56:45 -08001112 mCreationTimeMillis,
Hall Liuef98bf82020-01-09 15:22:44 -08001113 mContactDisplayName,
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001114 mCallDirection,
1115 mCallerNumberVerificationStatus);
Ihab Awade63fadb2014-07-09 21:52:04 -07001116 }
1117
1118 /** {@hide} */
1119 public Details(
Sailesh Nepal1bef3392016-01-24 18:21:53 -08001120 String telecomCallId,
Ihab Awade63fadb2014-07-09 21:52:04 -07001121 Uri handle,
1122 int handlePresentation,
1123 String callerDisplayName,
1124 int callerDisplayNamePresentation,
Evan Charlton8c8a0622014-07-20 12:31:00 -07001125 PhoneAccountHandle accountHandle,
Ihab Awade63fadb2014-07-09 21:52:04 -07001126 int capabilities,
Andrew Lee223ad142014-08-27 16:33:08 -07001127 int properties,
Andrew Lee7f3d41f2014-09-11 17:33:16 -07001128 DisconnectCause disconnectCause,
Ihab Awade63fadb2014-07-09 21:52:04 -07001129 long connectTimeMillis,
Andrew Lee85f5d422014-07-11 17:22:03 -07001130 GatewayInfo gatewayInfo,
Evan Charlton5b49ade2014-07-15 17:03:20 -07001131 int videoState,
Nancy Chen10798dc2014-08-08 14:00:25 -07001132 StatusHints statusHints,
Santos Cordon6b7f9552015-05-27 17:21:45 -07001133 Bundle extras,
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001134 Bundle intentExtras,
Tyler Gunnd081f042018-12-04 12:56:45 -08001135 long creationTimeMillis,
Hall Liuef98bf82020-01-09 15:22:44 -08001136 String contactDisplayName,
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001137 int callDirection,
1138 int callerNumberVerificationStatus) {
Sailesh Nepal1bef3392016-01-24 18:21:53 -08001139 mTelecomCallId = telecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07001140 mHandle = handle;
1141 mHandlePresentation = handlePresentation;
1142 mCallerDisplayName = callerDisplayName;
1143 mCallerDisplayNamePresentation = callerDisplayNamePresentation;
Evan Charlton8c8a0622014-07-20 12:31:00 -07001144 mAccountHandle = accountHandle;
Ihab Awad5d0410f2014-07-30 10:07:40 -07001145 mCallCapabilities = capabilities;
Andrew Lee223ad142014-08-27 16:33:08 -07001146 mCallProperties = properties;
Andrew Lee7f3d41f2014-09-11 17:33:16 -07001147 mDisconnectCause = disconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -07001148 mConnectTimeMillis = connectTimeMillis;
1149 mGatewayInfo = gatewayInfo;
Andrew Lee85f5d422014-07-11 17:22:03 -07001150 mVideoState = videoState;
Evan Charlton5b49ade2014-07-15 17:03:20 -07001151 mStatusHints = statusHints;
Nancy Chen10798dc2014-08-08 14:00:25 -07001152 mExtras = extras;
Santos Cordon6b7f9552015-05-27 17:21:45 -07001153 mIntentExtras = intentExtras;
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001154 mCreationTimeMillis = creationTimeMillis;
Hall Liuef98bf82020-01-09 15:22:44 -08001155 mContactDisplayName = contactDisplayName;
Tyler Gunn94f8f112018-12-17 09:56:11 -08001156 mCallDirection = callDirection;
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001157 mCallerNumberVerificationStatus = callerNumberVerificationStatus;
Ihab Awade63fadb2014-07-09 21:52:04 -07001158 }
Sailesh Nepal1bef3392016-01-24 18:21:53 -08001159
1160 /** {@hide} */
1161 public static Details createFromParcelableCall(ParcelableCall parcelableCall) {
1162 return new Details(
1163 parcelableCall.getId(),
1164 parcelableCall.getHandle(),
1165 parcelableCall.getHandlePresentation(),
1166 parcelableCall.getCallerDisplayName(),
1167 parcelableCall.getCallerDisplayNamePresentation(),
1168 parcelableCall.getAccountHandle(),
1169 parcelableCall.getCapabilities(),
1170 parcelableCall.getProperties(),
1171 parcelableCall.getDisconnectCause(),
1172 parcelableCall.getConnectTimeMillis(),
1173 parcelableCall.getGatewayInfo(),
1174 parcelableCall.getVideoState(),
1175 parcelableCall.getStatusHints(),
1176 parcelableCall.getExtras(),
Tyler Gunnc0bf6de2017-03-17 11:27:09 -07001177 parcelableCall.getIntentExtras(),
Tyler Gunnd081f042018-12-04 12:56:45 -08001178 parcelableCall.getCreationTimeMillis(),
Hall Liuef98bf82020-01-09 15:22:44 -08001179 parcelableCall.getContactDisplayName(),
Tyler Gunnd57d76c2019-09-24 14:53:23 -07001180 parcelableCall.getCallDirection(),
1181 parcelableCall.getCallerNumberVerificationStatus());
Sailesh Nepal1bef3392016-01-24 18:21:53 -08001182 }
Santos Cordon3c20d632016-02-25 16:12:35 -08001183
1184 @Override
1185 public String toString() {
1186 StringBuilder sb = new StringBuilder();
Tyler Gunn3cd820f2018-11-30 14:21:18 -08001187 sb.append("[id: ");
1188 sb.append(mTelecomCallId);
1189 sb.append(", pa: ");
Santos Cordon3c20d632016-02-25 16:12:35 -08001190 sb.append(mAccountHandle);
1191 sb.append(", hdl: ");
Tyler Gunn3cd820f2018-11-30 14:21:18 -08001192 sb.append(Log.piiHandle(mHandle));
1193 sb.append(", hdlPres: ");
1194 sb.append(mHandlePresentation);
1195 sb.append(", videoState: ");
1196 sb.append(VideoProfile.videoStateToString(mVideoState));
Santos Cordon3c20d632016-02-25 16:12:35 -08001197 sb.append(", caps: ");
1198 sb.append(capabilitiesToString(mCallCapabilities));
1199 sb.append(", props: ");
Tyler Gunn720c6642016-03-22 09:02:47 -07001200 sb.append(propertiesToString(mCallProperties));
Santos Cordon3c20d632016-02-25 16:12:35 -08001201 sb.append("]");
1202 return sb.toString();
1203 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001204 }
1205
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001206 /**
1207 * Defines callbacks which inform the {@link InCallService} of changes to a {@link Call}.
1208 * These callbacks can originate from the Telecom framework, or a {@link ConnectionService}
1209 * implementation.
1210 * <p>
1211 * You can handle these callbacks by extending the {@link Callback} class and overriding the
1212 * callbacks that your {@link InCallService} is interested in. The callback methods include the
1213 * {@link Call} for which the callback applies, allowing reuse of a single instance of your
1214 * {@link Callback} implementation, if desired.
1215 * <p>
1216 * Use {@link Call#registerCallback(Callback)} to register your callback(s). Ensure
1217 * {@link Call#unregisterCallback(Callback)} is called when you no longer require callbacks
1218 * (typically in {@link InCallService#onCallRemoved(Call)}).
1219 * Note: Callbacks which occur before you call {@link Call#registerCallback(Callback)} will not
1220 * reach your implementation of {@link Callback}, so it is important to register your callback
1221 * as soon as your {@link InCallService} is notified of a new call via
1222 * {@link InCallService#onCallAdded(Call)}.
1223 */
Andrew Leeda80c872015-04-15 14:09:50 -07001224 public static abstract class Callback {
Ihab Awade63fadb2014-07-09 21:52:04 -07001225 /**
Sanket Padawea8eddd42017-11-03 11:07:35 -07001226 * @hide
1227 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001228 @IntDef(prefix = { "HANDOVER_" },
1229 value = {HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_NOT_SUPPORTED,
Tyler Gunn5c60d712018-03-16 09:53:44 -07001230 HANDOVER_FAILURE_USER_REJECTED, HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL,
Tyler Gunn9d127732018-03-02 15:45:51 -08001231 HANDOVER_FAILURE_UNKNOWN})
Sanket Padawea8eddd42017-11-03 11:07:35 -07001232 @Retention(RetentionPolicy.SOURCE)
1233 public @interface HandoverFailureErrors {}
1234
1235 /**
1236 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the app
Tyler Gunn9d127732018-03-02 15:45:51 -08001237 * to handover the call to rejects the handover request.
1238 * <p>
1239 * Will be returned when {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} is called
1240 * and the destination {@link PhoneAccountHandle}'s {@link ConnectionService} returns a
1241 * {@code null} {@link Connection} from
1242 * {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
1243 * ConnectionRequest)}.
1244 * <p>
1245 * For more information on call handovers, see
1246 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001247 */
1248 public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1;
1249
1250 /**
Tyler Gunn9d127732018-03-02 15:45:51 -08001251 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
1252 * is initiated but the source or destination app does not support handover.
1253 * <p>
1254 * Will be returned when a handover is requested via
1255 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)} and the destination
1256 * {@link PhoneAccountHandle} does not declare
1257 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}. May also be returned when a handover is
1258 * requested at the {@link PhoneAccountHandle} for the current call (i.e. the source call's
1259 * {@link Details#getAccountHandle()}) does not declare
1260 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}.
1261 * <p>
1262 * For more information on call handovers, see
1263 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001264 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001265 public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001266
1267 /**
Tyler Gunn9d127732018-03-02 15:45:51 -08001268 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the remote
1269 * user rejects the handover request.
1270 * <p>
1271 * For more information on call handovers, see
1272 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001273 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001274 public static final int HANDOVER_FAILURE_USER_REJECTED = 3;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001275
Sanket Padawe85291f62017-12-01 13:59:27 -08001276 /**
1277 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there
1278 * is ongoing emergency call.
Tyler Gunn9d127732018-03-02 15:45:51 -08001279 * <p>
1280 * This error code is returned when {@link #handoverTo(PhoneAccountHandle, int, Bundle)} is
1281 * called on an emergency call, or if any other call is an emergency call.
1282 * <p>
1283 * Handovers are not permitted while there are ongoing emergency calls.
1284 * <p>
1285 * For more information on call handovers, see
1286 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawe85291f62017-12-01 13:59:27 -08001287 */
Tyler Gunn5c60d712018-03-16 09:53:44 -07001288 public static final int HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL = 4;
Sanket Padawe85291f62017-12-01 13:59:27 -08001289
Tyler Gunn9d127732018-03-02 15:45:51 -08001290 /**
1291 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
1292 * fails for an unknown reason.
1293 * <p>
1294 * For more information on call handovers, see
1295 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
1296 */
1297 public static final int HANDOVER_FAILURE_UNKNOWN = 5;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001298
1299 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001300 * Invoked when the state of this {@code Call} has changed. See {@link #getState()}.
1301 *
Ihab Awade63fadb2014-07-09 21:52:04 -07001302 * @param call The {@code Call} invoking this method.
1303 * @param state The new state of the {@code Call}.
1304 */
1305 public void onStateChanged(Call call, int state) {}
1306
1307 /**
1308 * Invoked when the parent of this {@code Call} has changed. See {@link #getParent()}.
1309 *
1310 * @param call The {@code Call} invoking this method.
1311 * @param parent The new parent of the {@code Call}.
1312 */
1313 public void onParentChanged(Call call, Call parent) {}
1314
1315 /**
1316 * Invoked when the children of this {@code Call} have changed. See {@link #getChildren()}.
1317 *
1318 * @param call The {@code Call} invoking this method.
1319 * @param children The new children of the {@code Call}.
1320 */
1321 public void onChildrenChanged(Call call, List<Call> children) {}
1322
1323 /**
1324 * Invoked when the details of this {@code Call} have changed. See {@link #getDetails()}.
1325 *
1326 * @param call The {@code Call} invoking this method.
1327 * @param details A {@code Details} object describing the {@code Call}.
1328 */
1329 public void onDetailsChanged(Call call, Details details) {}
1330
1331 /**
1332 * Invoked when the text messages that can be used as responses to the incoming
1333 * {@code Call} are loaded from the relevant database.
1334 * See {@link #getCannedTextResponses()}.
1335 *
1336 * @param call The {@code Call} invoking this method.
1337 * @param cannedTextResponses The text messages useable as responses.
1338 */
1339 public void onCannedTextResponsesLoaded(Call call, List<String> cannedTextResponses) {}
1340
1341 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001342 * Invoked when the post-dial sequence in the outgoing {@code Call} has reached a pause
1343 * character. This causes the post-dial signals to stop pending user confirmation. An
1344 * implementation should present this choice to the user and invoke
1345 * {@link #postDialContinue(boolean)} when the user makes the choice.
1346 *
1347 * @param call The {@code Call} invoking this method.
1348 * @param remainingPostDialSequence The post-dial characters that remain to be sent.
1349 */
1350 public void onPostDialWait(Call call, String remainingPostDialSequence) {}
1351
1352 /**
Andrew Lee50aca232014-07-22 16:41:54 -07001353 * Invoked when the {@code Call.VideoCall} of the {@code Call} has changed.
Ihab Awade63fadb2014-07-09 21:52:04 -07001354 *
1355 * @param call The {@code Call} invoking this method.
Andrew Lee50aca232014-07-22 16:41:54 -07001356 * @param videoCall The {@code Call.VideoCall} associated with the {@code Call}.
Ihab Awade63fadb2014-07-09 21:52:04 -07001357 */
Andrew Lee50aca232014-07-22 16:41:54 -07001358 public void onVideoCallChanged(Call call, InCallService.VideoCall videoCall) {}
Ihab Awade63fadb2014-07-09 21:52:04 -07001359
1360 /**
1361 * Invoked when the {@code Call} is destroyed. Clients should refrain from cleaning
1362 * up their UI for the {@code Call} in response to state transitions. Specifically,
1363 * clients should not assume that a {@link #onStateChanged(Call, int)} with a state of
1364 * {@link #STATE_DISCONNECTED} is the final notification the {@code Call} will send. Rather,
1365 * clients should wait for this method to be invoked.
1366 *
1367 * @param call The {@code Call} being destroyed.
1368 */
1369 public void onCallDestroyed(Call call) {}
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001370
1371 /**
1372 * Invoked upon changes to the set of {@code Call}s with which this {@code Call} can be
1373 * conferenced.
1374 *
1375 * @param call The {@code Call} being updated.
1376 * @param conferenceableCalls The {@code Call}s with which this {@code Call} can be
1377 * conferenced.
1378 */
1379 public void onConferenceableCallsChanged(Call call, List<Call> conferenceableCalls) {}
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001380
1381 /**
Tyler Gunn5567d742019-10-31 13:04:37 -07001382 * Invoked when a {@link Call} receives an event from its associated {@link Connection} or
1383 * {@link Conference}.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001384 * <p>
1385 * Where possible, the Call should make an attempt to handle {@link Connection} events which
1386 * are part of the {@code android.telecom.*} namespace. The Call should ignore any events
1387 * it does not wish to handle. Unexpected events should be handled gracefully, as it is
1388 * possible that a {@link ConnectionService} has defined its own Connection events which a
1389 * Call is not aware of.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001390 * <p>
Tyler Gunn5567d742019-10-31 13:04:37 -07001391 * See {@link Connection#sendConnectionEvent(String, Bundle)},
1392 * {@link Conference#sendConferenceEvent(String, Bundle)}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001393 *
1394 * @param call The {@code Call} receiving the event.
1395 * @param event The event.
1396 * @param extras Extras associated with the connection event.
1397 */
1398 public void onConnectionEvent(Call call, String event, Bundle extras) {}
Hall Liu95d55872017-01-25 17:12:49 -08001399
1400 /**
1401 * Invoked when the RTT mode changes for this call.
1402 * @param call The call whose RTT mode has changed.
1403 * @param mode the new RTT mode, one of
1404 * {@link RttCall#RTT_MODE_FULL}, {@link RttCall#RTT_MODE_HCO},
1405 * or {@link RttCall#RTT_MODE_VCO}
1406 */
1407 public void onRttModeChanged(Call call, int mode) {}
1408
1409 /**
1410 * Invoked when the call's RTT status changes, either from off to on or from on to off.
1411 * @param call The call whose RTT status has changed.
1412 * @param enabled whether RTT is now enabled or disabled
1413 * @param rttCall the {@link RttCall} object to use for reading and writing if RTT is now
1414 * on, null otherwise.
1415 */
1416 public void onRttStatusChanged(Call call, boolean enabled, RttCall rttCall) {}
1417
1418 /**
1419 * Invoked when the remote end of the connection has requested that an RTT communication
1420 * channel be opened. A response to this should be sent via {@link #respondToRttRequest}
1421 * with the same ID that this method is invoked with.
1422 * @param call The call which the RTT request was placed on
1423 * @param id The ID of the request.
1424 */
1425 public void onRttRequest(Call call, int id) {}
Hall Liu57006aa2017-02-06 10:49:48 -08001426
1427 /**
1428 * Invoked when the RTT session failed to initiate for some reason, including rejection
1429 * by the remote party.
1430 * @param call The call which the RTT initiation failure occurred on.
1431 * @param reason One of the status codes defined in
1432 * {@link android.telecom.Connection.RttModifyStatus}, with the exception of
1433 * {@link android.telecom.Connection.RttModifyStatus#SESSION_MODIFY_REQUEST_SUCCESS}.
1434 */
1435 public void onRttInitiationFailure(Call call, int reason) {}
Sanket Padawea8eddd42017-11-03 11:07:35 -07001436
1437 /**
1438 * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
1439 * has completed successfully.
Tyler Gunn9d127732018-03-02 15:45:51 -08001440 * <p>
1441 * For a full discussion of the handover process and the APIs involved, see
1442 * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
1443 *
Sanket Padawea8eddd42017-11-03 11:07:35 -07001444 * @param call The call which had initiated handover.
1445 */
1446 public void onHandoverComplete(Call call) {}
1447
1448 /**
1449 * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
1450 * has failed.
Tyler Gunn9d127732018-03-02 15:45:51 -08001451 * <p>
1452 * For a full discussion of the handover process and the APIs involved, see
1453 * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
1454 *
Sanket Padawea8eddd42017-11-03 11:07:35 -07001455 * @param call The call which had initiated handover.
Tyler Gunn9d127732018-03-02 15:45:51 -08001456 * @param failureReason Error reason for failure.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001457 */
1458 public void onHandoverFailed(Call call, @HandoverFailureErrors int failureReason) {}
Hall Liu95d55872017-01-25 17:12:49 -08001459 }
1460
1461 /**
1462 * A class that holds the state that describes the state of the RTT channel to the remote
1463 * party, if it is active.
1464 */
1465 public static final class RttCall {
Hall Liu07094df2017-02-28 15:17:44 -08001466 /** @hide */
Hall Liu95d55872017-01-25 17:12:49 -08001467 @Retention(RetentionPolicy.SOURCE)
1468 @IntDef({RTT_MODE_INVALID, RTT_MODE_FULL, RTT_MODE_HCO, RTT_MODE_VCO})
1469 public @interface RttAudioMode {}
1470
1471 /**
1472 * For metrics use. Default value in the proto.
1473 * @hide
1474 */
1475 public static final int RTT_MODE_INVALID = 0;
1476
1477 /**
1478 * Indicates that there should be a bidirectional audio stream between the two parties
1479 * on the call.
1480 */
1481 public static final int RTT_MODE_FULL = 1;
1482
1483 /**
1484 * Indicates that the local user should be able to hear the audio stream from the remote
1485 * user, but not vice versa. Equivalent to muting the microphone.
1486 */
1487 public static final int RTT_MODE_HCO = 2;
1488
1489 /**
1490 * Indicates that the remote user should be able to hear the audio stream from the local
1491 * user, but not vice versa. Equivalent to setting the volume to zero.
1492 */
1493 public static final int RTT_MODE_VCO = 3;
1494
1495 private static final int READ_BUFFER_SIZE = 1000;
1496
1497 private InputStreamReader mReceiveStream;
1498 private OutputStreamWriter mTransmitStream;
1499 private int mRttMode;
1500 private final InCallAdapter mInCallAdapter;
Hall Liu57006aa2017-02-06 10:49:48 -08001501 private final String mTelecomCallId;
Hall Liu95d55872017-01-25 17:12:49 -08001502 private char[] mReadBuffer = new char[READ_BUFFER_SIZE];
1503
1504 /**
1505 * @hide
1506 */
Hall Liu57006aa2017-02-06 10:49:48 -08001507 public RttCall(String telecomCallId, InputStreamReader receiveStream,
1508 OutputStreamWriter transmitStream, int mode, InCallAdapter inCallAdapter) {
1509 mTelecomCallId = telecomCallId;
Hall Liu95d55872017-01-25 17:12:49 -08001510 mReceiveStream = receiveStream;
1511 mTransmitStream = transmitStream;
1512 mRttMode = mode;
1513 mInCallAdapter = inCallAdapter;
1514 }
1515
1516 /**
1517 * Returns the current RTT audio mode.
1518 * @return Current RTT audio mode. One of {@link #RTT_MODE_FULL}, {@link #RTT_MODE_VCO}, or
1519 * {@link #RTT_MODE_HCO}.
1520 */
1521 public int getRttAudioMode() {
1522 return mRttMode;
1523 }
1524
1525 /**
1526 * Sets the RTT audio mode. The requested mode change will be communicated through
1527 * {@link Callback#onRttModeChanged(Call, int)}.
1528 * @param mode The desired RTT audio mode, one of {@link #RTT_MODE_FULL},
1529 * {@link #RTT_MODE_VCO}, or {@link #RTT_MODE_HCO}.
1530 */
1531 public void setRttMode(@RttAudioMode int mode) {
Hall Liu57006aa2017-02-06 10:49:48 -08001532 mInCallAdapter.setRttMode(mTelecomCallId, mode);
Hall Liu95d55872017-01-25 17:12:49 -08001533 }
1534
1535 /**
1536 * Writes the string {@param input} into the outgoing text stream for this RTT call. Since
Hall Liudc46c852020-10-29 16:15:33 -07001537 * RTT transmits text in real-time, this method should be called once for each user action.
1538 * For example, when the user enters text as discrete characters using the keyboard, this
1539 * method should be called once for each character. However, if the user enters text by
1540 * pasting or autocomplete, the entire contents of the pasted or autocompleted text should
1541 * be sent in one call to this method.
Hall Liu95d55872017-01-25 17:12:49 -08001542 *
1543 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1544 * lead to interleaved text.
1545 * @param input The message to send to the remote user.
1546 */
1547 public void write(String input) throws IOException {
1548 mTransmitStream.write(input);
1549 mTransmitStream.flush();
1550 }
1551
1552 /**
1553 * Reads a string from the remote user, blocking if there is no data available. Returns
1554 * {@code null} if the RTT conversation has been terminated and there is no further data
1555 * to read.
1556 *
1557 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1558 * lead to interleaved text.
1559 * @return A string containing text sent by the remote user, or {@code null} if the
1560 * conversation has been terminated or if there was an error while reading.
1561 */
Hall Liub1c8a772017-07-17 17:04:41 -07001562 public String read() {
1563 try {
1564 int numRead = mReceiveStream.read(mReadBuffer, 0, READ_BUFFER_SIZE);
1565 if (numRead < 0) {
1566 return null;
1567 }
1568 return new String(mReadBuffer, 0, numRead);
1569 } catch (IOException e) {
1570 Log.w(this, "Exception encountered when reading from InputStreamReader: %s", e);
Jeff Sharkey90396362017-06-12 16:26:53 -06001571 return null;
Hall Liuffa4a812017-03-02 16:11:00 -08001572 }
Hall Liuffa4a812017-03-02 16:11:00 -08001573 }
1574
1575 /**
1576 * Non-blocking version of {@link #read()}. Returns {@code null} if there is nothing to
1577 * be read.
1578 * @return A string containing text entered by the user, or {@code null} if the user has
1579 * not entered any new text yet.
1580 */
1581 public String readImmediately() throws IOException {
1582 if (mReceiveStream.ready()) {
Hall Liub1c8a772017-07-17 17:04:41 -07001583 int numRead = mReceiveStream.read(mReadBuffer, 0, READ_BUFFER_SIZE);
1584 if (numRead < 0) {
1585 return null;
1586 }
1587 return new String(mReadBuffer, 0, numRead);
Hall Liuffa4a812017-03-02 16:11:00 -08001588 } else {
Hall Liu95d55872017-01-25 17:12:49 -08001589 return null;
1590 }
1591 }
Hall Liue9041242018-02-09 16:40:03 -08001592
1593 /**
1594 * Closes the underlying file descriptors
1595 * @hide
1596 */
1597 public void close() {
1598 try {
1599 mReceiveStream.close();
1600 } catch (IOException e) {
1601 // ignore
1602 }
1603 try {
1604 mTransmitStream.close();
1605 } catch (IOException e) {
1606 // ignore
1607 }
1608 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001609 }
1610
Andrew Leeda80c872015-04-15 14:09:50 -07001611 /**
1612 * @deprecated Use {@code Call.Callback} instead.
1613 * @hide
1614 */
1615 @Deprecated
1616 @SystemApi
1617 public static abstract class Listener extends Callback { }
1618
Ihab Awade63fadb2014-07-09 21:52:04 -07001619 private final Phone mPhone;
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001620 private final String mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07001621 private final InCallAdapter mInCallAdapter;
Santos Cordon823fd3c2014-08-07 18:35:18 -07001622 private final List<String> mChildrenIds = new ArrayList<>();
Ihab Awade63fadb2014-07-09 21:52:04 -07001623 private final List<Call> mChildren = new ArrayList<>();
1624 private final List<Call> mUnmodifiableChildren = Collections.unmodifiableList(mChildren);
Andrew Lee011728f2015-04-23 15:47:06 -07001625 private final List<CallbackRecord<Callback>> mCallbackRecords = new CopyOnWriteArrayList<>();
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001626 private final List<Call> mConferenceableCalls = new ArrayList<>();
1627 private final List<Call> mUnmodifiableConferenceableCalls =
1628 Collections.unmodifiableList(mConferenceableCalls);
1629
Santos Cordon823fd3c2014-08-07 18:35:18 -07001630 private boolean mChildrenCached;
1631 private String mParentId = null;
Hall Liuef98bf82020-01-09 15:22:44 -08001632 private String mActiveGenericConferenceChild = null;
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001633 private int mState;
Ihab Awade63fadb2014-07-09 21:52:04 -07001634 private List<String> mCannedTextResponses = null;
Tyler Gunnb88b3112016-11-09 10:19:23 -08001635 private String mCallingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08001636 private int mTargetSdkVersion;
Ihab Awade63fadb2014-07-09 21:52:04 -07001637 private String mRemainingPostDialSequence;
Tyler Gunn584ba6c2015-12-08 10:53:41 -08001638 private VideoCallImpl mVideoCallImpl;
Hall Liu95d55872017-01-25 17:12:49 -08001639 private RttCall mRttCall;
Ihab Awade63fadb2014-07-09 21:52:04 -07001640 private Details mDetails;
Tyler Gunndee56a82016-03-23 16:06:34 -07001641 private Bundle mExtras;
Ihab Awade63fadb2014-07-09 21:52:04 -07001642
1643 /**
1644 * Obtains the post-dial sequence remaining to be emitted by this {@code Call}, if any.
1645 *
1646 * @return The remaining post-dial sequence, or {@code null} if there is no post-dial sequence
1647 * remaining or this {@code Call} is not in a post-dial state.
1648 */
1649 public String getRemainingPostDialSequence() {
1650 return mRemainingPostDialSequence;
1651 }
1652
1653 /**
1654 * Instructs this {@link #STATE_RINGING} {@code Call} to answer.
Andrew Lee8da4c3c2014-07-16 10:11:42 -07001655 * @param videoState The video state in which to answer the call.
Ihab Awade63fadb2014-07-09 21:52:04 -07001656 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001657 public void answer(@VideoProfile.VideoState int videoState) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001658 mInCallAdapter.answerCall(mTelecomCallId, videoState);
Ihab Awade63fadb2014-07-09 21:52:04 -07001659 }
1660
1661 /**
Pooja Jaind34698d2017-12-28 14:15:31 +05301662 * Instructs this {@link #STATE_RINGING} {@code Call} to deflect.
1663 *
1664 * @param address The address to which the call will be deflected.
1665 */
1666 public void deflect(Uri address) {
1667 mInCallAdapter.deflectCall(mTelecomCallId, address);
1668 }
1669
1670 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001671 * Instructs this {@link #STATE_RINGING} {@code Call} to reject.
1672 *
1673 * @param rejectWithMessage Whether to reject with a text message.
1674 * @param textMessage An optional text message with which to respond.
1675 */
1676 public void reject(boolean rejectWithMessage, String textMessage) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001677 mInCallAdapter.rejectCall(mTelecomCallId, rejectWithMessage, textMessage);
Ihab Awade63fadb2014-07-09 21:52:04 -07001678 }
1679
1680 /**
Tyler Gunnfacfdee2020-01-23 13:10:37 -08001681 * Instructs the {@link ConnectionService} providing this {@link #STATE_RINGING} call that the
1682 * user has chosen to reject the call and has indicated a reason why the call is being rejected.
1683 *
1684 * @param rejectReason the reason the call is being rejected.
1685 */
1686 public void reject(@RejectReason int rejectReason) {
1687 mInCallAdapter.rejectCall(mTelecomCallId, rejectReason);
1688 }
1689
1690 /**
Ravi Palurif4b38e72020-02-05 12:35:41 +05301691 * Instructs this {@code Call} to be transferred to another number.
1692 *
1693 * @param targetNumber The address to which the call will be transferred.
Tyler Gunn460360d2020-07-29 10:21:45 -07001694 * @param isConfirmationRequired if {@code true} it will initiate a confirmed transfer,
1695 * if {@code false}, it will initiate an unconfirmed transfer.
Ravi Palurif4b38e72020-02-05 12:35:41 +05301696 *
1697 * @hide
1698 */
1699 public void transfer(@NonNull Uri targetNumber, boolean isConfirmationRequired) {
1700 mInCallAdapter.transferCall(mTelecomCallId, targetNumber, isConfirmationRequired);
1701 }
1702
1703 /**
1704 * Instructs this {@code Call} to be transferred to another ongoing call.
1705 * This will initiate CONSULTATIVE transfer.
1706 * @param toCall The other ongoing {@code Call} to which this call will be transferred.
1707 *
1708 * @hide
1709 */
1710 public void transfer(@NonNull android.telecom.Call toCall) {
1711 mInCallAdapter.transferCall(mTelecomCallId, toCall.mTelecomCallId);
1712 }
1713
1714 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001715 * Instructs this {@code Call} to disconnect.
1716 */
1717 public void disconnect() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001718 mInCallAdapter.disconnectCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001719 }
1720
1721 /**
1722 * Instructs this {@code Call} to go on hold.
1723 */
1724 public void hold() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001725 mInCallAdapter.holdCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001726 }
1727
1728 /**
1729 * Instructs this {@link #STATE_HOLDING} call to release from hold.
1730 */
1731 public void unhold() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001732 mInCallAdapter.unholdCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001733 }
1734
1735 /**
Hall Liu6dfa2492019-10-01 17:20:39 -07001736 * Instructs Telecom to put the call into the background audio processing state.
Tyler Gunn460b7d42020-05-15 10:19:32 -07001737 * <p>
Hall Liu6dfa2492019-10-01 17:20:39 -07001738 * This method can be called either when the call is in {@link #STATE_RINGING} or
1739 * {@link #STATE_ACTIVE}. After Telecom acknowledges the request by setting the call's state to
1740 * {@link #STATE_AUDIO_PROCESSING}, your app may setup the audio paths with the audio stack in
1741 * order to capture and play audio on the call stream.
Tyler Gunn460b7d42020-05-15 10:19:32 -07001742 * <p>
Hall Liu6dfa2492019-10-01 17:20:39 -07001743 * This method can only be called by the default dialer app.
Tyler Gunn460b7d42020-05-15 10:19:32 -07001744 * <p>
1745 * Apps built with SDK version {@link android.os.Build.VERSION_CODES#R} or later which are using
1746 * the microphone as part of audio processing should specify the foreground service type using
1747 * the attribute {@link android.R.attr#foregroundServiceType} in the {@link InCallService}
1748 * service element of the app's manifest file.
1749 * The {@link ServiceInfo#FOREGROUND_SERVICE_TYPE_MICROPHONE} attribute should be specified.
1750 * @see <a href="https://developer.android.com/preview/privacy/foreground-service-types">
1751 * the Android Developer Site</a> for more information.
Hall Liu6dfa2492019-10-01 17:20:39 -07001752 * @hide
1753 */
1754 @SystemApi
Hall Liu6dfa2492019-10-01 17:20:39 -07001755 public void enterBackgroundAudioProcessing() {
1756 if (mState != STATE_ACTIVE && mState != STATE_RINGING) {
1757 throw new IllegalStateException("Call must be active or ringing");
1758 }
1759 mInCallAdapter.enterBackgroundAudioProcessing(mTelecomCallId);
1760 }
1761
1762 /**
1763 * Instructs Telecom to come out of the background audio processing state requested by
1764 * {@link #enterBackgroundAudioProcessing()} or from the call screening service.
1765 *
1766 * This method can only be called when the call is in {@link #STATE_AUDIO_PROCESSING}.
1767 *
1768 * @param shouldRing If true, Telecom will put the call into the
1769 * {@link #STATE_SIMULATED_RINGING} state and notify other apps that there is
1770 * a ringing call. Otherwise, the call will go into {@link #STATE_ACTIVE}
1771 * immediately.
1772 * @hide
1773 */
1774 @SystemApi
Hall Liu6dfa2492019-10-01 17:20:39 -07001775 public void exitBackgroundAudioProcessing(boolean shouldRing) {
1776 if (mState != STATE_AUDIO_PROCESSING) {
1777 throw new IllegalStateException("Call must in the audio processing state");
1778 }
1779 mInCallAdapter.exitBackgroundAudioProcessing(mTelecomCallId, shouldRing);
1780 }
1781
1782 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001783 * Instructs this {@code Call} to play a dual-tone multi-frequency signaling (DTMF) tone.
1784 *
1785 * Any other currently playing DTMF tone in the specified call is immediately stopped.
1786 *
1787 * @param digit A character representing the DTMF digit for which to play the tone. This
1788 * value must be one of {@code '0'} through {@code '9'}, {@code '*'} or {@code '#'}.
1789 */
1790 public void playDtmfTone(char digit) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001791 mInCallAdapter.playDtmfTone(mTelecomCallId, digit);
Ihab Awade63fadb2014-07-09 21:52:04 -07001792 }
1793
1794 /**
1795 * Instructs this {@code Call} to stop any dual-tone multi-frequency signaling (DTMF) tone
1796 * currently playing.
1797 *
1798 * DTMF tones are played by calling {@link #playDtmfTone(char)}. If no DTMF tone is
1799 * currently playing, this method will do nothing.
1800 */
1801 public void stopDtmfTone() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001802 mInCallAdapter.stopDtmfTone(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001803 }
1804
1805 /**
1806 * Instructs this {@code Call} to continue playing a post-dial DTMF string.
1807 *
1808 * A post-dial DTMF string is a string of digits entered after a phone number, when dialed,
1809 * that are immediately sent as DTMF tones to the recipient as soon as the connection is made.
Ihab Awade63fadb2014-07-09 21:52:04 -07001810 *
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001811 * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_PAUSE} symbol, this
Ihab Awade63fadb2014-07-09 21:52:04 -07001812 * {@code Call} will temporarily pause playing the tones for a pre-defined period of time.
1813 *
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001814 * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_WAIT} symbol, this
Andrew Leeda80c872015-04-15 14:09:50 -07001815 * {@code Call} will pause playing the tones and notify callbacks via
1816 * {@link Callback#onPostDialWait(Call, String)}. At this point, the in-call app
Ihab Awade63fadb2014-07-09 21:52:04 -07001817 * should display to the user an indication of this state and an affordance to continue
1818 * the postdial sequence. When the user decides to continue the postdial sequence, the in-call
1819 * app should invoke the {@link #postDialContinue(boolean)} method.
1820 *
1821 * @param proceed Whether or not to continue with the post-dial sequence.
1822 */
1823 public void postDialContinue(boolean proceed) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001824 mInCallAdapter.postDialContinue(mTelecomCallId, proceed);
Ihab Awade63fadb2014-07-09 21:52:04 -07001825 }
1826
1827 /**
Evan Charlton8c8a0622014-07-20 12:31:00 -07001828 * Notifies this {@code Call} that an account has been selected and to proceed with placing
Nancy Chen36c62f32014-10-21 18:36:39 -07001829 * an outgoing call. Optionally sets this account as the default account.
Nancy Chen5da0fd52014-07-08 14:16:17 -07001830 */
Nancy Chen36c62f32014-10-21 18:36:39 -07001831 public void phoneAccountSelected(PhoneAccountHandle accountHandle, boolean setDefault) {
1832 mInCallAdapter.phoneAccountSelected(mTelecomCallId, accountHandle, setDefault);
Nancy Chen5da0fd52014-07-08 14:16:17 -07001833
1834 }
1835
1836 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001837 * Instructs this {@code Call} to enter a conference.
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001838 *
1839 * @param callToConferenceWith The other call with which to conference.
Ihab Awade63fadb2014-07-09 21:52:04 -07001840 */
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001841 public void conference(Call callToConferenceWith) {
1842 if (callToConferenceWith != null) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001843 mInCallAdapter.conference(mTelecomCallId, callToConferenceWith.mTelecomCallId);
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001844 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001845 }
1846
1847 /**
1848 * Instructs this {@code Call} to split from any conference call with which it may be
1849 * connected.
1850 */
1851 public void splitFromConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001852 mInCallAdapter.splitFromConference(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001853 }
1854
1855 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001856 * Merges the calls within this conference. See {@link Details#CAPABILITY_MERGE_CONFERENCE}.
Santos Cordona4868042014-09-04 17:39:22 -07001857 */
1858 public void mergeConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001859 mInCallAdapter.mergeConference(mTelecomCallId);
Santos Cordona4868042014-09-04 17:39:22 -07001860 }
1861
1862 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001863 * Swaps the calls within this conference. See {@link Details#CAPABILITY_SWAP_CONFERENCE}.
Santos Cordona4868042014-09-04 17:39:22 -07001864 */
1865 public void swapConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001866 mInCallAdapter.swapConference(mTelecomCallId);
Santos Cordona4868042014-09-04 17:39:22 -07001867 }
1868
1869 /**
Ravi Paluri404babb2020-01-23 19:02:44 +05301870 * Pulls participants to existing call by forming a conference call.
1871 * See {@link Details#CAPABILITY_ADD_PARTICIPANT}.
1872 *
1873 * @param participants participants to be pulled to existing call.
1874 */
1875 public void addConferenceParticipants(@NonNull List<Uri> participants) {
1876 mInCallAdapter.addConferenceParticipants(mTelecomCallId, participants);
1877 }
1878
1879 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001880 * Initiates a request to the {@link ConnectionService} to pull an external call to the local
1881 * device.
1882 * <p>
1883 * Calls to this method are ignored if the call does not have the
1884 * {@link Call.Details#PROPERTY_IS_EXTERNAL_CALL} property set.
1885 * <p>
1886 * An {@link InCallService} will only see calls which support this method if it has the
1887 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
1888 * in its manifest.
1889 */
1890 public void pullExternalCall() {
1891 // If this isn't an external call, ignore the request.
1892 if (!mDetails.hasProperty(Details.PROPERTY_IS_EXTERNAL_CALL)) {
1893 return;
1894 }
1895
1896 mInCallAdapter.pullExternalCall(mTelecomCallId);
1897 }
1898
1899 /**
1900 * Sends a {@code Call} event from this {@code Call} to the associated {@link Connection} in
1901 * the {@link ConnectionService}.
1902 * <p>
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001903 * Call events are used to communicate point in time information from an {@link InCallService}
1904 * to a {@link ConnectionService}. A {@link ConnectionService} implementation could define
1905 * events which enable the {@link InCallService}, for example, toggle a unique feature of the
1906 * {@link ConnectionService}.
1907 * <p>
1908 * A {@link ConnectionService} can communicate to the {@link InCallService} using
1909 * {@link Connection#sendConnectionEvent(String, Bundle)}.
1910 * <p>
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001911 * Events are exposed to {@link ConnectionService} implementations via
1912 * {@link android.telecom.Connection#onCallEvent(String, Bundle)}.
1913 * <p>
1914 * No assumptions should be made as to how a {@link ConnectionService} will handle these events.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001915 * The {@link InCallService} must assume that the {@link ConnectionService} could chose to
1916 * ignore some events altogether.
1917 * <p>
1918 * Events should be fully qualified (e.g., {@code com.example.event.MY_EVENT}) to avoid
1919 * conflicts between {@link InCallService} implementations. Further, {@link InCallService}
1920 * implementations shall not re-purpose events in the {@code android.*} namespace, nor shall
1921 * they define their own event types in this namespace. When defining a custom event type,
1922 * ensure the contents of the extras {@link Bundle} is clearly defined. Extra keys for this
1923 * bundle should be named similar to the event type (e.g. {@code com.example.extra.MY_EXTRA}).
1924 * <p>
1925 * When defining events and the associated extras, it is important to keep their behavior
1926 * consistent when the associated {@link InCallService} is updated. Support for deprecated
1927 * events/extras should me maintained to ensure backwards compatibility with older
1928 * {@link ConnectionService} implementations which were built to support the older behavior.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001929 *
1930 * @param event The connection event.
1931 * @param extras Bundle containing extra information associated with the event.
1932 */
1933 public void sendCallEvent(String event, Bundle extras) {
Sanket Padawef6a9e5b2018-01-05 14:26:16 -08001934 mInCallAdapter.sendCallEvent(mTelecomCallId, event, mTargetSdkVersion, extras);
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001935 }
1936
1937 /**
Hall Liu95d55872017-01-25 17:12:49 -08001938 * Sends an RTT upgrade request to the remote end of the connection. Success is not
1939 * guaranteed, and notification of success will be via the
1940 * {@link Callback#onRttStatusChanged(Call, boolean, RttCall)} callback.
1941 */
1942 public void sendRttRequest() {
Hall Liu57006aa2017-02-06 10:49:48 -08001943 mInCallAdapter.sendRttRequest(mTelecomCallId);
Hall Liu95d55872017-01-25 17:12:49 -08001944 }
1945
1946 /**
1947 * Responds to an RTT request received via the {@link Callback#onRttRequest(Call, int)} )}
1948 * callback.
1949 * The ID used here should be the same as the ID that was received via the callback.
1950 * @param id The request ID received via {@link Callback#onRttRequest(Call, int)}
1951 * @param accept {@code true} if the RTT request should be accepted, {@code false} otherwise.
1952 */
1953 public void respondToRttRequest(int id, boolean accept) {
Hall Liu57006aa2017-02-06 10:49:48 -08001954 mInCallAdapter.respondToRttRequest(mTelecomCallId, id, accept);
Hall Liu95d55872017-01-25 17:12:49 -08001955 }
1956
1957 /**
Sanket Padawea8eddd42017-11-03 11:07:35 -07001958 * Initiates a handover of this {@link Call} to the {@link ConnectionService} identified
1959 * by {@code toHandle}. The videoState specified indicates the desired video state after the
1960 * handover.
1961 * <p>
Tyler Gunn9d127732018-03-02 15:45:51 -08001962 * A call handover is the process where an ongoing call is transferred from one app (i.e.
1963 * {@link ConnectionService} to another app. The user could, for example, choose to continue a
1964 * mobile network call in a video calling app. The mobile network call via the Telephony stack
1965 * is referred to as the source of the handover, and the video calling app is referred to as the
1966 * destination.
1967 * <p>
1968 * When considering a handover scenario the device this method is called on is considered the
1969 * <em>initiating</em> device (since the user initiates the handover from this device), and the
1970 * other device is considered the <em>receiving</em> device.
1971 * <p>
1972 * When this method is called on the <em>initiating</em> device, the Telecom framework will bind
1973 * to the {@link ConnectionService} defined by the {@code toHandle} {@link PhoneAccountHandle}
1974 * and invoke
1975 * {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
1976 * ConnectionRequest)} to inform the destination app that a request has been made to handover a
1977 * call to it. The app returns an instance of {@link Connection} to represent the handover call
1978 * At this point the app should display UI to indicate to the user that a call
1979 * handover is in process.
1980 * <p>
1981 * The destination app is responsible for communicating the handover request from the
1982 * <em>initiating</em> device to the <em>receiving</em> device.
1983 * <p>
1984 * When the app on the <em>receiving</em> device receives the handover request, it calls
1985 * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to continue the handover
1986 * process from the <em>initiating</em> device to the <em>receiving</em> device. At this point
1987 * the destination app on the <em>receiving</em> device should show UI to allow the user to
1988 * choose whether they want to continue their call in the destination app.
1989 * <p>
1990 * When the destination app on the <em>receiving</em> device calls
1991 * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}, Telecom will bind to its
1992 * {@link ConnectionService} and call
1993 * {@link ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle,
1994 * ConnectionRequest)} to inform it of the handover request. The app returns an instance of
1995 * {@link Connection} to represent the handover call.
1996 * <p>
1997 * If the user of the <em>receiving</em> device accepts the handover, the app calls
1998 * {@link Connection#setActive()} to complete the handover process; Telecom will disconnect the
1999 * original call. If the user rejects the handover, the app calls
2000 * {@link Connection#setDisconnected(DisconnectCause)} and specifies a {@link DisconnectCause}
2001 * of {@link DisconnectCause#CANCELED} to indicate that the handover has been cancelled.
2002 * <p>
2003 * Telecom will only allow handovers from {@link PhoneAccount}s which declare
2004 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}. Similarly, the {@link PhoneAccount}
2005 * specified by {@code toHandle} must declare {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}.
2006 * <p>
2007 * Errors in the handover process are reported to the {@link InCallService} via
2008 * {@link Callback#onHandoverFailed(Call, int)}. Errors in the handover process are reported to
2009 * the involved {@link ConnectionService}s via
2010 * {@link ConnectionService#onHandoverFailed(ConnectionRequest, int)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07002011 *
2012 * @param toHandle {@link PhoneAccountHandle} of the {@link ConnectionService} to handover
2013 * this call to.
Tyler Gunn9d127732018-03-02 15:45:51 -08002014 * @param videoState Indicates the video state desired after the handover (see the
2015 * {@code STATE_*} constants defined in {@link VideoProfile}).
Sanket Padawea8eddd42017-11-03 11:07:35 -07002016 * @param extras Bundle containing extra information to be passed to the
2017 * {@link ConnectionService}
2018 */
Tyler Gunn9d127732018-03-02 15:45:51 -08002019 public void handoverTo(PhoneAccountHandle toHandle, @VideoProfile.VideoState int videoState,
2020 Bundle extras) {
Sanket Padawea8eddd42017-11-03 11:07:35 -07002021 mInCallAdapter.handoverTo(mTelecomCallId, toHandle, videoState, extras);
2022 }
2023
2024 /**
Hall Liu95d55872017-01-25 17:12:49 -08002025 * Terminate the RTT session on this call. The resulting state change will be notified via
2026 * the {@link Callback#onRttStatusChanged(Call, boolean, RttCall)} callback.
2027 */
2028 public void stopRtt() {
Hall Liu57006aa2017-02-06 10:49:48 -08002029 mInCallAdapter.stopRtt(mTelecomCallId);
Hall Liu95d55872017-01-25 17:12:49 -08002030 }
2031
2032 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07002033 * Adds some extras to this {@link Call}. Existing keys are replaced and new ones are
2034 * added.
2035 * <p>
2036 * No assumptions should be made as to how an In-Call UI or service will handle these
2037 * extras. Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
2038 *
2039 * @param extras The extras to add.
2040 */
2041 public final void putExtras(Bundle extras) {
2042 if (extras == null) {
2043 return;
2044 }
2045
2046 if (mExtras == null) {
2047 mExtras = new Bundle();
2048 }
2049 mExtras.putAll(extras);
2050 mInCallAdapter.putExtras(mTelecomCallId, extras);
2051 }
2052
2053 /**
2054 * Adds a boolean extra to this {@link Call}.
2055 *
2056 * @param key The extra key.
2057 * @param value The value.
2058 * @hide
2059 */
2060 public final void putExtra(String key, boolean value) {
2061 if (mExtras == null) {
2062 mExtras = new Bundle();
2063 }
2064 mExtras.putBoolean(key, value);
2065 mInCallAdapter.putExtra(mTelecomCallId, key, value);
2066 }
2067
2068 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002069 * Adds an integer extra to this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07002070 *
2071 * @param key The extra key.
2072 * @param value The value.
2073 * @hide
2074 */
2075 public final void putExtra(String key, int value) {
2076 if (mExtras == null) {
2077 mExtras = new Bundle();
2078 }
2079 mExtras.putInt(key, value);
2080 mInCallAdapter.putExtra(mTelecomCallId, key, value);
2081 }
2082
2083 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002084 * Adds a string extra to this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07002085 *
2086 * @param key The extra key.
2087 * @param value The value.
2088 * @hide
2089 */
2090 public final void putExtra(String key, String value) {
2091 if (mExtras == null) {
2092 mExtras = new Bundle();
2093 }
2094 mExtras.putString(key, value);
2095 mInCallAdapter.putExtra(mTelecomCallId, key, value);
2096 }
2097
2098 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002099 * Removes extras from this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07002100 *
2101 * @param keys The keys of the extras to remove.
2102 */
2103 public final void removeExtras(List<String> keys) {
2104 if (mExtras != null) {
2105 for (String key : keys) {
2106 mExtras.remove(key);
2107 }
2108 if (mExtras.size() == 0) {
2109 mExtras = null;
2110 }
2111 }
2112 mInCallAdapter.removeExtras(mTelecomCallId, keys);
2113 }
2114
2115 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002116 * Removes extras from this {@link Call}.
2117 *
2118 * @param keys The keys of the extras to remove.
2119 */
2120 public final void removeExtras(String ... keys) {
2121 removeExtras(Arrays.asList(keys));
2122 }
2123
2124 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07002125 * Obtains the parent of this {@code Call} in a conference, if any.
2126 *
2127 * @return The parent {@code Call}, or {@code null} if this {@code Call} is not a
2128 * child of any conference {@code Call}s.
2129 */
2130 public Call getParent() {
Santos Cordon823fd3c2014-08-07 18:35:18 -07002131 if (mParentId != null) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002132 return mPhone.internalGetCallByTelecomId(mParentId);
Santos Cordon823fd3c2014-08-07 18:35:18 -07002133 }
2134 return null;
Ihab Awade63fadb2014-07-09 21:52:04 -07002135 }
2136
2137 /**
2138 * Obtains the children of this conference {@code Call}, if any.
2139 *
2140 * @return The children of this {@code Call} if this {@code Call} is a conference, or an empty
2141 * {@code List} otherwise.
2142 */
2143 public List<Call> getChildren() {
Santos Cordon823fd3c2014-08-07 18:35:18 -07002144 if (!mChildrenCached) {
2145 mChildrenCached = true;
2146 mChildren.clear();
2147
2148 for(String id : mChildrenIds) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002149 Call call = mPhone.internalGetCallByTelecomId(id);
Santos Cordon823fd3c2014-08-07 18:35:18 -07002150 if (call == null) {
2151 // At least one child was still not found, so do not save true for "cached"
2152 mChildrenCached = false;
2153 } else {
2154 mChildren.add(call);
2155 }
2156 }
2157 }
2158
Ihab Awade63fadb2014-07-09 21:52:04 -07002159 return mUnmodifiableChildren;
2160 }
2161
2162 /**
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002163 * Returns the list of {@code Call}s with which this {@code Call} is allowed to conference.
2164 *
2165 * @return The list of conferenceable {@code Call}s.
2166 */
2167 public List<Call> getConferenceableCalls() {
2168 return mUnmodifiableConferenceableCalls;
2169 }
2170
2171 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07002172 * Obtains the state of this {@code Call}.
2173 *
2174 * @return A state value, chosen from the {@code STATE_*} constants.
2175 */
2176 public int getState() {
2177 return mState;
2178 }
2179
2180 /**
Hall Liuef98bf82020-01-09 15:22:44 -08002181 * Returns the child {@link Call} in a generic conference that is currently active.
Hall Liu135e53aa2020-02-27 18:34:11 -08002182 *
2183 * A "generic conference" is the mechanism used to support two simultaneous calls on a device
2184 * in CDMA networks. It is effectively equivalent to having one call active and one call on hold
2185 * in GSM or IMS calls. This method returns the currently active call.
2186 *
2187 * In a generic conference, the network exposes the conference to us as a single call, and we
2188 * switch between talking to the two participants using a CDMA flash command. Since the network
2189 * exposes no additional information about the call, the only way we know which caller we're
2190 * currently talking to is by keeping track of the flash commands that we've sent to the
2191 * network.
2192 *
Hall Liuef98bf82020-01-09 15:22:44 -08002193 * For calls that are not generic conferences, or when the generic conference has more than
2194 * 2 children, returns {@code null}.
2195 * @see Details#PROPERTY_GENERIC_CONFERENCE
2196 * @return The active child call.
2197 */
2198 public @Nullable Call getGenericConferenceActiveChildCall() {
2199 if (mActiveGenericConferenceChild != null) {
2200 return mPhone.internalGetCallByTelecomId(mActiveGenericConferenceChild);
2201 }
2202 return null;
2203 }
2204
2205 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07002206 * Obtains a list of canned, pre-configured message responses to present to the user as
Tyler Gunn434fc2c2020-10-06 14:23:54 -07002207 * ways of rejecting an incoming {@code Call} using via a text message.
2208 * <p>
2209 * <em>Note:</em> Since canned responses may be loaded from the file system, they are not
2210 * guaranteed to be present when this {@link Call} is first added to the {@link InCallService}
2211 * via {@link InCallService#onCallAdded(Call)}. The callback
2212 * {@link Call.Callback#onCannedTextResponsesLoaded(Call, List)} will be called when/if canned
2213 * responses for the call become available.
Ihab Awade63fadb2014-07-09 21:52:04 -07002214 *
2215 * @see #reject(boolean, String)
2216 *
2217 * @return A list of canned text message responses.
2218 */
2219 public List<String> getCannedTextResponses() {
2220 return mCannedTextResponses;
2221 }
2222
2223 /**
2224 * Obtains an object that can be used to display video from this {@code Call}.
2225 *
Andrew Lee50aca232014-07-22 16:41:54 -07002226 * @return An {@code Call.VideoCall}.
Ihab Awade63fadb2014-07-09 21:52:04 -07002227 */
Andrew Lee50aca232014-07-22 16:41:54 -07002228 public InCallService.VideoCall getVideoCall() {
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002229 return mVideoCallImpl;
Ihab Awade63fadb2014-07-09 21:52:04 -07002230 }
2231
2232 /**
2233 * Obtains an object containing call details.
2234 *
2235 * @return A {@link Details} object. Depending on the state of the {@code Call}, the
2236 * result may be {@code null}.
2237 */
2238 public Details getDetails() {
2239 return mDetails;
2240 }
2241
2242 /**
Hall Liu95d55872017-01-25 17:12:49 -08002243 * Returns this call's RttCall object. The {@link RttCall} instance is used to send and
2244 * receive RTT text data, as well as to change the RTT mode.
2245 * @return A {@link Call.RttCall}. {@code null} if there is no active RTT connection.
2246 */
2247 public @Nullable RttCall getRttCall() {
2248 return mRttCall;
2249 }
2250
2251 /**
2252 * Returns whether this call has an active RTT connection.
2253 * @return true if there is a connection, false otherwise.
2254 */
2255 public boolean isRttActive() {
Hall Liue9041242018-02-09 16:40:03 -08002256 return mRttCall != null && mDetails.hasProperty(Details.PROPERTY_RTT);
Hall Liu95d55872017-01-25 17:12:49 -08002257 }
2258
2259 /**
Andrew Leeda80c872015-04-15 14:09:50 -07002260 * Registers a callback to this {@code Call}.
2261 *
2262 * @param callback A {@code Callback}.
2263 */
2264 public void registerCallback(Callback callback) {
Andrew Lee011728f2015-04-23 15:47:06 -07002265 registerCallback(callback, new Handler());
2266 }
2267
2268 /**
2269 * Registers a callback to this {@code Call}.
2270 *
2271 * @param callback A {@code Callback}.
2272 * @param handler A handler which command and status changes will be delivered to.
2273 */
2274 public void registerCallback(Callback callback, Handler handler) {
2275 unregisterCallback(callback);
Roshan Pius1ca62072015-07-07 17:34:51 -07002276 // Don't allow new callback registration if the call is already being destroyed.
2277 if (callback != null && handler != null && mState != STATE_DISCONNECTED) {
Andrew Lee011728f2015-04-23 15:47:06 -07002278 mCallbackRecords.add(new CallbackRecord<Callback>(callback, handler));
2279 }
Andrew Leeda80c872015-04-15 14:09:50 -07002280 }
2281
2282 /**
2283 * Unregisters a callback from this {@code Call}.
2284 *
2285 * @param callback A {@code Callback}.
2286 */
2287 public void unregisterCallback(Callback callback) {
Roshan Pius1ca62072015-07-07 17:34:51 -07002288 // Don't allow callback deregistration if the call is already being destroyed.
2289 if (callback != null && mState != STATE_DISCONNECTED) {
Andrew Lee011728f2015-04-23 15:47:06 -07002290 for (CallbackRecord<Callback> record : mCallbackRecords) {
2291 if (record.getCallback() == callback) {
2292 mCallbackRecords.remove(record);
2293 break;
2294 }
2295 }
Andrew Leeda80c872015-04-15 14:09:50 -07002296 }
2297 }
2298
Santos Cordon3c20d632016-02-25 16:12:35 -08002299 @Override
2300 public String toString() {
2301 return new StringBuilder().
2302 append("Call [id: ").
2303 append(mTelecomCallId).
2304 append(", state: ").
2305 append(stateToString(mState)).
2306 append(", details: ").
2307 append(mDetails).
2308 append("]").toString();
2309 }
2310
2311 /**
2312 * @param state An integer value of a {@code STATE_*} constant.
2313 * @return A string representation of the value.
2314 */
2315 private static String stateToString(int state) {
2316 switch (state) {
2317 case STATE_NEW:
2318 return "NEW";
2319 case STATE_RINGING:
2320 return "RINGING";
2321 case STATE_DIALING:
2322 return "DIALING";
2323 case STATE_ACTIVE:
2324 return "ACTIVE";
2325 case STATE_HOLDING:
2326 return "HOLDING";
2327 case STATE_DISCONNECTED:
2328 return "DISCONNECTED";
2329 case STATE_CONNECTING:
2330 return "CONNECTING";
2331 case STATE_DISCONNECTING:
2332 return "DISCONNECTING";
2333 case STATE_SELECT_PHONE_ACCOUNT:
2334 return "SELECT_PHONE_ACCOUNT";
Hall Liu4e35b642019-10-14 17:50:45 -07002335 case STATE_SIMULATED_RINGING:
2336 return "SIMULATED_RINGING";
2337 case STATE_AUDIO_PROCESSING:
2338 return "AUDIO_PROCESSING";
Santos Cordon3c20d632016-02-25 16:12:35 -08002339 default:
2340 Log.w(Call.class, "Unknown state %d", state);
2341 return "UNKNOWN";
2342 }
2343 }
2344
Andrew Leeda80c872015-04-15 14:09:50 -07002345 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07002346 * Adds a listener to this {@code Call}.
2347 *
2348 * @param listener A {@code Listener}.
Andrew Leeda80c872015-04-15 14:09:50 -07002349 * @deprecated Use {@link #registerCallback} instead.
2350 * @hide
Ihab Awade63fadb2014-07-09 21:52:04 -07002351 */
Andrew Leeda80c872015-04-15 14:09:50 -07002352 @Deprecated
2353 @SystemApi
Ihab Awade63fadb2014-07-09 21:52:04 -07002354 public void addListener(Listener listener) {
Andrew Leeda80c872015-04-15 14:09:50 -07002355 registerCallback(listener);
Ihab Awade63fadb2014-07-09 21:52:04 -07002356 }
2357
2358 /**
2359 * Removes a listener from this {@code Call}.
2360 *
2361 * @param listener A {@code Listener}.
Andrew Leeda80c872015-04-15 14:09:50 -07002362 * @deprecated Use {@link #unregisterCallback} instead.
2363 * @hide
Ihab Awade63fadb2014-07-09 21:52:04 -07002364 */
Andrew Leeda80c872015-04-15 14:09:50 -07002365 @Deprecated
2366 @SystemApi
Ihab Awade63fadb2014-07-09 21:52:04 -07002367 public void removeListener(Listener listener) {
Andrew Leeda80c872015-04-15 14:09:50 -07002368 unregisterCallback(listener);
Ihab Awade63fadb2014-07-09 21:52:04 -07002369 }
2370
2371 /** {@hide} */
Tyler Gunn159f35c2017-03-02 09:28:37 -08002372 Call(Phone phone, String telecomCallId, InCallAdapter inCallAdapter, String callingPackage,
2373 int targetSdkVersion) {
Ihab Awade63fadb2014-07-09 21:52:04 -07002374 mPhone = phone;
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002375 mTelecomCallId = telecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002376 mInCallAdapter = inCallAdapter;
2377 mState = STATE_NEW;
Tyler Gunnb88b3112016-11-09 10:19:23 -08002378 mCallingPackage = callingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08002379 mTargetSdkVersion = targetSdkVersion;
Ihab Awade63fadb2014-07-09 21:52:04 -07002380 }
2381
2382 /** {@hide} */
Tyler Gunnb88b3112016-11-09 10:19:23 -08002383 Call(Phone phone, String telecomCallId, InCallAdapter inCallAdapter, int state,
Tyler Gunn159f35c2017-03-02 09:28:37 -08002384 String callingPackage, int targetSdkVersion) {
Shriram Ganeshddf570e2015-05-31 09:18:48 -07002385 mPhone = phone;
2386 mTelecomCallId = telecomCallId;
2387 mInCallAdapter = inCallAdapter;
2388 mState = state;
Tyler Gunnb88b3112016-11-09 10:19:23 -08002389 mCallingPackage = callingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08002390 mTargetSdkVersion = targetSdkVersion;
Shriram Ganeshddf570e2015-05-31 09:18:48 -07002391 }
2392
2393 /** {@hide} */
Ihab Awade63fadb2014-07-09 21:52:04 -07002394 final String internalGetCallId() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002395 return mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002396 }
2397
2398 /** {@hide} */
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002399 final void internalUpdate(ParcelableCall parcelableCall, Map<String, Call> callIdMap) {
Tyler Gunnb88b3112016-11-09 10:19:23 -08002400
Ihab Awade63fadb2014-07-09 21:52:04 -07002401 // First, we update the internal state as far as possible before firing any updates.
Sailesh Nepal1bef3392016-01-24 18:21:53 -08002402 Details details = Details.createFromParcelableCall(parcelableCall);
Ihab Awade63fadb2014-07-09 21:52:04 -07002403 boolean detailsChanged = !Objects.equals(mDetails, details);
2404 if (detailsChanged) {
2405 mDetails = details;
2406 }
2407
2408 boolean cannedTextResponsesChanged = false;
Santos Cordon88b771d2014-07-19 13:10:40 -07002409 if (mCannedTextResponses == null && parcelableCall.getCannedSmsResponses() != null
2410 && !parcelableCall.getCannedSmsResponses().isEmpty()) {
2411 mCannedTextResponses =
2412 Collections.unmodifiableList(parcelableCall.getCannedSmsResponses());
Yorke Leee886f632015-08-04 13:43:31 -07002413 cannedTextResponsesChanged = true;
Ihab Awade63fadb2014-07-09 21:52:04 -07002414 }
2415
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002416 IVideoProvider previousVideoProvider = mVideoCallImpl == null ? null :
2417 mVideoCallImpl.getVideoProvider();
2418 IVideoProvider newVideoProvider = parcelableCall.getVideoProvider();
2419
2420 // parcelableCall.isVideoCallProviderChanged is only true when we have a video provider
2421 // specified; so we should check if the actual IVideoProvider changes as well.
2422 boolean videoCallChanged = parcelableCall.isVideoCallProviderChanged()
2423 && !Objects.equals(previousVideoProvider, newVideoProvider);
Andrew Lee50aca232014-07-22 16:41:54 -07002424 if (videoCallChanged) {
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002425 if (mVideoCallImpl != null) {
2426 mVideoCallImpl.destroy();
2427 }
2428 mVideoCallImpl = parcelableCall.isVideoCallProviderChanged() ?
2429 parcelableCall.getVideoCallImpl(mCallingPackage, mTargetSdkVersion) : null;
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002430 }
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002431
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002432 if (mVideoCallImpl != null) {
2433 mVideoCallImpl.setVideoState(getDetails().getVideoState());
Ihab Awade63fadb2014-07-09 21:52:04 -07002434 }
2435
Santos Cordone3c507b2015-04-23 14:44:19 -07002436 int state = parcelableCall.getState();
Hall Liu31de23d2019-10-11 15:38:29 -07002437 if (mTargetSdkVersion < Phone.SDK_VERSION_R && state == Call.STATE_SIMULATED_RINGING) {
2438 state = Call.STATE_RINGING;
2439 }
Ihab Awade63fadb2014-07-09 21:52:04 -07002440 boolean stateChanged = mState != state;
2441 if (stateChanged) {
2442 mState = state;
2443 }
2444
Santos Cordon823fd3c2014-08-07 18:35:18 -07002445 String parentId = parcelableCall.getParentCallId();
2446 boolean parentChanged = !Objects.equals(mParentId, parentId);
2447 if (parentChanged) {
2448 mParentId = parentId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002449 }
2450
Santos Cordon823fd3c2014-08-07 18:35:18 -07002451 List<String> childCallIds = parcelableCall.getChildCallIds();
2452 boolean childrenChanged = !Objects.equals(childCallIds, mChildrenIds);
2453 if (childrenChanged) {
2454 mChildrenIds.clear();
2455 mChildrenIds.addAll(parcelableCall.getChildCallIds());
2456 mChildrenCached = false;
Ihab Awade63fadb2014-07-09 21:52:04 -07002457 }
2458
Hall Liuef98bf82020-01-09 15:22:44 -08002459 String activeChildCallId = parcelableCall.getActiveChildCallId();
2460 boolean activeChildChanged = !Objects.equals(activeChildCallId,
2461 mActiveGenericConferenceChild);
2462 if (activeChildChanged) {
2463 mActiveGenericConferenceChild = activeChildCallId;
2464 }
2465
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002466 List<String> conferenceableCallIds = parcelableCall.getConferenceableCallIds();
2467 List<Call> conferenceableCalls = new ArrayList<Call>(conferenceableCallIds.size());
2468 for (String otherId : conferenceableCallIds) {
2469 if (callIdMap.containsKey(otherId)) {
2470 conferenceableCalls.add(callIdMap.get(otherId));
2471 }
2472 }
2473
2474 if (!Objects.equals(mConferenceableCalls, conferenceableCalls)) {
2475 mConferenceableCalls.clear();
2476 mConferenceableCalls.addAll(conferenceableCalls);
2477 fireConferenceableCallsChanged();
2478 }
2479
Hall Liu95d55872017-01-25 17:12:49 -08002480 boolean isRttChanged = false;
2481 boolean rttModeChanged = false;
Hall Liue9041242018-02-09 16:40:03 -08002482 if (parcelableCall.getIsRttCallChanged()
2483 && mDetails.hasProperty(Details.PROPERTY_RTT)) {
Hall Liu95d55872017-01-25 17:12:49 -08002484 ParcelableRttCall parcelableRttCall = parcelableCall.getParcelableRttCall();
2485 InputStreamReader receiveStream = new InputStreamReader(
2486 new ParcelFileDescriptor.AutoCloseInputStream(
2487 parcelableRttCall.getReceiveStream()),
2488 StandardCharsets.UTF_8);
2489 OutputStreamWriter transmitStream = new OutputStreamWriter(
2490 new ParcelFileDescriptor.AutoCloseOutputStream(
2491 parcelableRttCall.getTransmitStream()),
2492 StandardCharsets.UTF_8);
Hall Liu57006aa2017-02-06 10:49:48 -08002493 RttCall newRttCall = new Call.RttCall(mTelecomCallId,
Hall Liu95d55872017-01-25 17:12:49 -08002494 receiveStream, transmitStream, parcelableRttCall.getRttMode(), mInCallAdapter);
2495 if (mRttCall == null) {
2496 isRttChanged = true;
2497 } else if (mRttCall.getRttAudioMode() != newRttCall.getRttAudioMode()) {
2498 rttModeChanged = true;
2499 }
2500 mRttCall = newRttCall;
2501 } else if (mRttCall != null && parcelableCall.getParcelableRttCall() == null
2502 && parcelableCall.getIsRttCallChanged()) {
2503 isRttChanged = true;
2504 mRttCall = null;
2505 }
2506
Ihab Awade63fadb2014-07-09 21:52:04 -07002507 // Now we fire updates, ensuring that any client who listens to any of these notifications
2508 // gets the most up-to-date state.
2509
2510 if (stateChanged) {
2511 fireStateChanged(mState);
2512 }
2513 if (detailsChanged) {
2514 fireDetailsChanged(mDetails);
2515 }
2516 if (cannedTextResponsesChanged) {
2517 fireCannedTextResponsesLoaded(mCannedTextResponses);
2518 }
Andrew Lee50aca232014-07-22 16:41:54 -07002519 if (videoCallChanged) {
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002520 fireVideoCallChanged(mVideoCallImpl);
Ihab Awade63fadb2014-07-09 21:52:04 -07002521 }
Santos Cordon823fd3c2014-08-07 18:35:18 -07002522 if (parentChanged) {
2523 fireParentChanged(getParent());
2524 }
Hall Liuef98bf82020-01-09 15:22:44 -08002525 if (childrenChanged || activeChildChanged) {
Santos Cordon823fd3c2014-08-07 18:35:18 -07002526 fireChildrenChanged(getChildren());
2527 }
Hall Liu95d55872017-01-25 17:12:49 -08002528 if (isRttChanged) {
2529 fireOnIsRttChanged(mRttCall != null, mRttCall);
2530 }
2531 if (rttModeChanged) {
2532 fireOnRttModeChanged(mRttCall.getRttAudioMode());
2533 }
Ihab Awade63fadb2014-07-09 21:52:04 -07002534
2535 // If we have transitioned to DISCONNECTED, that means we need to notify clients and
2536 // remove ourselves from the Phone. Note that we do this after completing all state updates
2537 // so a client can cleanly transition all their UI to the state appropriate for a
2538 // DISCONNECTED Call while still relying on the existence of that Call in the Phone's list.
2539 if (mState == STATE_DISCONNECTED) {
2540 fireCallDestroyed();
Ihab Awade63fadb2014-07-09 21:52:04 -07002541 }
2542 }
2543
2544 /** {@hide} */
Ihab Awade63fadb2014-07-09 21:52:04 -07002545 final void internalSetPostDialWait(String remaining) {
2546 mRemainingPostDialSequence = remaining;
2547 firePostDialWait(mRemainingPostDialSequence);
2548 }
2549
Sailesh Nepal2ab88cc2014-07-18 14:49:18 -07002550 /** {@hide} */
Santos Cordonf30d7e92014-08-26 09:54:33 -07002551 final void internalSetDisconnected() {
2552 if (mState != Call.STATE_DISCONNECTED) {
2553 mState = Call.STATE_DISCONNECTED;
2554 fireStateChanged(mState);
2555 fireCallDestroyed();
Santos Cordonf30d7e92014-08-26 09:54:33 -07002556 }
2557 }
2558
Tyler Gunn876dbfb2016-03-14 15:18:07 -07002559 /** {@hide} */
2560 final void internalOnConnectionEvent(String event, Bundle extras) {
2561 fireOnConnectionEvent(event, extras);
2562 }
2563
Hall Liu95d55872017-01-25 17:12:49 -08002564 /** {@hide} */
2565 final void internalOnRttUpgradeRequest(final int requestId) {
2566 for (CallbackRecord<Callback> record : mCallbackRecords) {
2567 final Call call = this;
2568 final Callback callback = record.getCallback();
2569 record.getHandler().post(() -> callback.onRttRequest(call, requestId));
2570 }
2571 }
2572
Hall Liu57006aa2017-02-06 10:49:48 -08002573 /** @hide */
2574 final void internalOnRttInitiationFailure(int reason) {
2575 for (CallbackRecord<Callback> record : mCallbackRecords) {
2576 final Call call = this;
2577 final Callback callback = record.getCallback();
2578 record.getHandler().post(() -> callback.onRttInitiationFailure(call, reason));
2579 }
2580 }
2581
Sanket Padawe85291f62017-12-01 13:59:27 -08002582 /** {@hide} */
2583 final void internalOnHandoverFailed(int error) {
2584 for (CallbackRecord<Callback> record : mCallbackRecords) {
2585 final Call call = this;
2586 final Callback callback = record.getCallback();
2587 record.getHandler().post(() -> callback.onHandoverFailed(call, error));
2588 }
2589 }
2590
Tyler Gunn858bfaf2018-01-22 15:17:54 -08002591 /** {@hide} */
2592 final void internalOnHandoverComplete() {
2593 for (CallbackRecord<Callback> record : mCallbackRecords) {
2594 final Call call = this;
2595 final Callback callback = record.getCallback();
2596 record.getHandler().post(() -> callback.onHandoverComplete(call));
2597 }
2598 }
2599
Andrew Lee011728f2015-04-23 15:47:06 -07002600 private void fireStateChanged(final int newState) {
2601 for (CallbackRecord<Callback> record : mCallbackRecords) {
2602 final Call call = this;
2603 final Callback callback = record.getCallback();
2604 record.getHandler().post(new Runnable() {
2605 @Override
2606 public void run() {
2607 callback.onStateChanged(call, newState);
2608 }
2609 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002610 }
2611 }
2612
Andrew Lee011728f2015-04-23 15:47:06 -07002613 private void fireParentChanged(final Call newParent) {
2614 for (CallbackRecord<Callback> record : mCallbackRecords) {
2615 final Call call = this;
2616 final Callback callback = record.getCallback();
2617 record.getHandler().post(new Runnable() {
2618 @Override
2619 public void run() {
2620 callback.onParentChanged(call, newParent);
2621 }
2622 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002623 }
2624 }
2625
Andrew Lee011728f2015-04-23 15:47:06 -07002626 private void fireChildrenChanged(final List<Call> children) {
2627 for (CallbackRecord<Callback> record : mCallbackRecords) {
2628 final Call call = this;
2629 final Callback callback = record.getCallback();
2630 record.getHandler().post(new Runnable() {
2631 @Override
2632 public void run() {
2633 callback.onChildrenChanged(call, children);
2634 }
2635 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002636 }
2637 }
2638
Andrew Lee011728f2015-04-23 15:47:06 -07002639 private void fireDetailsChanged(final Details details) {
2640 for (CallbackRecord<Callback> record : mCallbackRecords) {
2641 final Call call = this;
2642 final Callback callback = record.getCallback();
2643 record.getHandler().post(new Runnable() {
2644 @Override
2645 public void run() {
2646 callback.onDetailsChanged(call, details);
2647 }
2648 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002649 }
2650 }
2651
Andrew Lee011728f2015-04-23 15:47:06 -07002652 private void fireCannedTextResponsesLoaded(final List<String> cannedTextResponses) {
2653 for (CallbackRecord<Callback> record : mCallbackRecords) {
2654 final Call call = this;
2655 final Callback callback = record.getCallback();
2656 record.getHandler().post(new Runnable() {
2657 @Override
2658 public void run() {
2659 callback.onCannedTextResponsesLoaded(call, cannedTextResponses);
2660 }
2661 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002662 }
2663 }
2664
Andrew Lee011728f2015-04-23 15:47:06 -07002665 private void fireVideoCallChanged(final InCallService.VideoCall videoCall) {
2666 for (CallbackRecord<Callback> record : mCallbackRecords) {
2667 final Call call = this;
2668 final Callback callback = record.getCallback();
2669 record.getHandler().post(new Runnable() {
2670 @Override
2671 public void run() {
2672 callback.onVideoCallChanged(call, videoCall);
2673 }
2674 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002675 }
2676 }
2677
Andrew Lee011728f2015-04-23 15:47:06 -07002678 private void firePostDialWait(final String remainingPostDialSequence) {
2679 for (CallbackRecord<Callback> record : mCallbackRecords) {
2680 final Call call = this;
2681 final Callback callback = record.getCallback();
2682 record.getHandler().post(new Runnable() {
2683 @Override
2684 public void run() {
2685 callback.onPostDialWait(call, remainingPostDialSequence);
2686 }
2687 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002688 }
2689 }
2690
2691 private void fireCallDestroyed() {
Roshan Pius1ca62072015-07-07 17:34:51 -07002692 /**
2693 * To preserve the ordering of the Call's onCallDestroyed callback and Phone's
2694 * onCallRemoved callback, we remove this call from the Phone's record
2695 * only once all of the registered onCallDestroyed callbacks are executed.
2696 * All the callbacks get removed from our records as a part of this operation
2697 * since onCallDestroyed is the final callback.
2698 */
2699 final Call call = this;
2700 if (mCallbackRecords.isEmpty()) {
2701 // No callbacks registered, remove the call from Phone's record.
2702 mPhone.internalRemoveCall(call);
2703 }
2704 for (final CallbackRecord<Callback> record : mCallbackRecords) {
Andrew Lee011728f2015-04-23 15:47:06 -07002705 final Callback callback = record.getCallback();
2706 record.getHandler().post(new Runnable() {
2707 @Override
2708 public void run() {
Roshan Pius1ca62072015-07-07 17:34:51 -07002709 boolean isFinalRemoval = false;
2710 RuntimeException toThrow = null;
2711 try {
2712 callback.onCallDestroyed(call);
2713 } catch (RuntimeException e) {
2714 toThrow = e;
2715 }
2716 synchronized(Call.this) {
2717 mCallbackRecords.remove(record);
2718 if (mCallbackRecords.isEmpty()) {
2719 isFinalRemoval = true;
2720 }
2721 }
2722 if (isFinalRemoval) {
2723 mPhone.internalRemoveCall(call);
2724 }
2725 if (toThrow != null) {
2726 throw toThrow;
2727 }
Andrew Lee011728f2015-04-23 15:47:06 -07002728 }
2729 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002730 }
2731 }
2732
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002733 private void fireConferenceableCallsChanged() {
Andrew Lee011728f2015-04-23 15:47:06 -07002734 for (CallbackRecord<Callback> record : mCallbackRecords) {
2735 final Call call = this;
2736 final Callback callback = record.getCallback();
2737 record.getHandler().post(new Runnable() {
2738 @Override
2739 public void run() {
2740 callback.onConferenceableCallsChanged(call, mUnmodifiableConferenceableCalls);
2741 }
2742 });
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002743 }
2744 }
Tyler Gunn1e9bfc62015-08-19 11:18:58 -07002745
2746 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -07002747 * Notifies listeners of an incoming connection event.
2748 * <p>
2749 * Connection events are issued via {@link Connection#sendConnectionEvent(String, Bundle)}.
2750 *
2751 * @param event
2752 * @param extras
2753 */
2754 private void fireOnConnectionEvent(final String event, final Bundle extras) {
2755 for (CallbackRecord<Callback> record : mCallbackRecords) {
2756 final Call call = this;
2757 final Callback callback = record.getCallback();
2758 record.getHandler().post(new Runnable() {
2759 @Override
2760 public void run() {
2761 callback.onConnectionEvent(call, event, extras);
2762 }
2763 });
2764 }
2765 }
2766
2767 /**
Hall Liu95d55872017-01-25 17:12:49 -08002768 * Notifies listeners of an RTT on/off change
2769 *
2770 * @param enabled True if RTT is now enabled, false otherwise
2771 */
2772 private void fireOnIsRttChanged(final boolean enabled, final RttCall rttCall) {
2773 for (CallbackRecord<Callback> record : mCallbackRecords) {
2774 final Call call = this;
2775 final Callback callback = record.getCallback();
2776 record.getHandler().post(() -> callback.onRttStatusChanged(call, enabled, rttCall));
2777 }
2778 }
2779
2780 /**
2781 * Notifies listeners of a RTT mode change
2782 *
2783 * @param mode The new RTT mode
2784 */
2785 private void fireOnRttModeChanged(final int mode) {
2786 for (CallbackRecord<Callback> record : mCallbackRecords) {
2787 final Call call = this;
2788 final Callback callback = record.getCallback();
2789 record.getHandler().post(() -> callback.onRttModeChanged(call, mode));
2790 }
2791 }
2792
2793 /**
Tyler Gunn1e9bfc62015-08-19 11:18:58 -07002794 * Determines if two bundles are equal.
2795 *
2796 * @param bundle The original bundle.
2797 * @param newBundle The bundle to compare with.
2798 * @retrun {@code true} if the bundles are equal, {@code false} otherwise.
2799 */
2800 private static boolean areBundlesEqual(Bundle bundle, Bundle newBundle) {
2801 if (bundle == null || newBundle == null) {
2802 return bundle == newBundle;
2803 }
2804
2805 if (bundle.size() != newBundle.size()) {
2806 return false;
2807 }
2808
2809 for(String key : bundle.keySet()) {
2810 if (key != null) {
2811 final Object value = bundle.get(key);
2812 final Object newValue = newBundle.get(key);
2813 if (!Objects.equals(value, newValue)) {
2814 return false;
2815 }
2816 }
2817 }
2818 return true;
2819 }
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002820}