blob: 3ecf8d73d0a621598a8b7d0623622df42aead039 [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;
20import android.annotation.Nullable;
Andrew Leeda80c872015-04-15 14:09:50 -070021import android.annotation.SystemApi;
Hall Liu6dfa2492019-10-01 17:20:39 -070022import android.annotation.TestApi;
Mathew Inwood42346d12018-08-01 11:33:05 +010023import android.annotation.UnsupportedAppUsage;
Ihab Awade63fadb2014-07-09 21:52:04 -070024import android.net.Uri;
Tyler Gunn6e3ecc42018-11-12 11:30:56 -080025import android.os.Build;
Nancy Chen10798dc2014-08-08 14:00:25 -070026import android.os.Bundle;
Andrew Lee011728f2015-04-23 15:47:06 -070027import android.os.Handler;
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -080028import android.os.IBinder;
Hall Liu95d55872017-01-25 17:12:49 -080029import android.os.ParcelFileDescriptor;
Ihab Awade63fadb2014-07-09 21:52:04 -070030
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -080031import com.android.internal.telecom.IVideoProvider;
32
Hall Liu95d55872017-01-25 17:12:49 -080033import java.io.IOException;
34import java.io.InputStreamReader;
35import java.io.OutputStreamWriter;
Hall Liu95d55872017-01-25 17:12:49 -080036import java.lang.annotation.Retention;
37import java.lang.annotation.RetentionPolicy;
38import java.nio.charset.StandardCharsets;
Ihab Awade63fadb2014-07-09 21:52:04 -070039import java.util.ArrayList;
Tyler Gunn071be6f2016-05-10 14:52:33 -070040import java.util.Arrays;
Ihab Awade63fadb2014-07-09 21:52:04 -070041import java.util.Collections;
42import java.util.List;
Santos Cordon7c7bc7f2014-07-28 18:15:48 -070043import java.util.Map;
Ihab Awade63fadb2014-07-09 21:52:04 -070044import java.util.Objects;
Jay Shrauner229e3822014-08-15 09:23:07 -070045import java.util.concurrent.CopyOnWriteArrayList;
Ihab Awade63fadb2014-07-09 21:52:04 -070046
47/**
48 * Represents an ongoing phone call that the in-call app should present to the user.
49 */
50public final class Call {
51 /**
52 * The state of a {@code Call} when newly created.
53 */
54 public static final int STATE_NEW = 0;
55
56 /**
57 * The state of an outgoing {@code Call} when dialing the remote number, but not yet connected.
58 */
59 public static final int STATE_DIALING = 1;
60
61 /**
62 * The state of an incoming {@code Call} when ringing locally, but not yet connected.
63 */
64 public static final int STATE_RINGING = 2;
65
66 /**
67 * The state of a {@code Call} when in a holding state.
68 */
69 public static final int STATE_HOLDING = 3;
70
71 /**
72 * The state of a {@code Call} when actively supporting conversation.
73 */
74 public static final int STATE_ACTIVE = 4;
75
76 /**
77 * The state of a {@code Call} when no further voice or other communication is being
78 * transmitted, the remote side has been or will inevitably be informed that the {@code Call}
79 * is no longer active, and the local data transport has or inevitably will release resources
80 * associated with this {@code Call}.
81 */
82 public static final int STATE_DISCONNECTED = 7;
83
Nancy Chen5da0fd52014-07-08 14:16:17 -070084 /**
Santos Cordone3c507b2015-04-23 14:44:19 -070085 * The state of an outgoing {@code Call} when waiting on user to select a
86 * {@link PhoneAccount} through which to place the call.
Nancy Chen5da0fd52014-07-08 14:16:17 -070087 */
Santos Cordone3c507b2015-04-23 14:44:19 -070088 public static final int STATE_SELECT_PHONE_ACCOUNT = 8;
89
90 /**
91 * @hide
92 * @deprecated use STATE_SELECT_PHONE_ACCOUNT.
93 */
94 @Deprecated
95 @SystemApi
96 public static final int STATE_PRE_DIAL_WAIT = STATE_SELECT_PHONE_ACCOUNT;
Nancy Chen5da0fd52014-07-08 14:16:17 -070097
Nancy Chene20930f2014-08-07 16:17:21 -070098 /**
Nancy Chene9b7a8e2014-08-08 14:26:27 -070099 * The initial state of an outgoing {@code Call}.
100 * Common transitions are to {@link #STATE_DIALING} state for a successful call or
101 * {@link #STATE_DISCONNECTED} if it failed.
Nancy Chene20930f2014-08-07 16:17:21 -0700102 */
103 public static final int STATE_CONNECTING = 9;
104
Nancy Chen513c8922014-09-17 14:47:20 -0700105 /**
Tyler Gunn4afc6af2014-10-07 10:14:55 -0700106 * The state of a {@code Call} when the user has initiated a disconnection of the call, but the
107 * call has not yet been disconnected by the underlying {@code ConnectionService}. The next
108 * state of the call is (potentially) {@link #STATE_DISCONNECTED}.
109 */
110 public static final int STATE_DISCONNECTING = 10;
111
112 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700113 * The state of an external call which is in the process of being pulled from a remote device to
114 * the local device.
115 * <p>
116 * A call can only be in this state if the {@link Details#PROPERTY_IS_EXTERNAL_CALL} property
117 * and {@link Details#CAPABILITY_CAN_PULL_CALL} capability are set on the call.
118 * <p>
119 * An {@link InCallService} will only see this state if it has the
120 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true} in its
121 * manifest.
122 */
123 public static final int STATE_PULLING_CALL = 11;
124
125 /**
Hall Liu6dfa2492019-10-01 17:20:39 -0700126 * The state of a call that is active with the network, but the audio from the call is
127 * being intercepted by an app on the local device. Telecom does not hold audio focus in this
128 * state, and the call will be invisible to the user except for a persistent notification.
129 */
130 public static final int STATE_AUDIO_PROCESSING = 12;
131
132 /**
133 * The state of a call that is being presented to the user after being in
134 * {@link #STATE_AUDIO_PROCESSING}. The call is still active with the network in this case, and
135 * Telecom will hold audio focus and play a ringtone if appropriate.
136 */
137 public static final int STATE_SIMULATED_RINGING = 13;
138
139 /**
Nancy Chen513c8922014-09-17 14:47:20 -0700140 * The key to retrieve the optional {@code PhoneAccount}s Telecom can bundle with its Call
141 * extras. Used to pass the phone accounts to display on the front end to the user in order to
142 * select phone accounts to (for example) place a call.
Hall Liu34d9e242018-11-21 17:05:58 -0800143 * @deprecated Use the list from {@link #EXTRA_SUGGESTED_PHONE_ACCOUNTS} instead.
Nancy Chen513c8922014-09-17 14:47:20 -0700144 */
Hall Liu34d9e242018-11-21 17:05:58 -0800145 @Deprecated
Nancy Chen513c8922014-09-17 14:47:20 -0700146 public static final String AVAILABLE_PHONE_ACCOUNTS = "selectPhoneAccountAccounts";
147
mike dooley4af561f2016-12-20 08:55:17 -0800148 /**
Hall Liu34d9e242018-11-21 17:05:58 -0800149 * Key for extra used to pass along a list of {@link PhoneAccountSuggestion}s to the in-call
150 * UI when a call enters the {@link #STATE_SELECT_PHONE_ACCOUNT} state. The list included here
151 * will have the same length and be in the same order as the list passed with
152 * {@link #AVAILABLE_PHONE_ACCOUNTS}.
153 */
154 public static final String EXTRA_SUGGESTED_PHONE_ACCOUNTS =
155 "android.telecom.extra.SUGGESTED_PHONE_ACCOUNTS";
156
157 /**
mike dooley91217422017-03-09 12:58:42 -0800158 * Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC)
159 * when the last outgoing emergency call was made. This is used to identify potential emergency
160 * callbacks.
mike dooley4af561f2016-12-20 08:55:17 -0800161 */
162 public static final String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS =
163 "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS";
164
Usman Abdullahb0dc29a2019-03-06 15:54:56 -0800165
166 /**
167 * Extra key used to indicate whether a {@link CallScreeningService} has requested to silence
168 * the ringtone for a call. If the {@link InCallService} declares
169 * {@link TelecomManager#METADATA_IN_CALL_SERVICE_RINGING} in its manifest, it should not
170 * play a ringtone for an incoming call with this extra key set.
171 */
172 public static final String EXTRA_SILENT_RINGING_REQUESTED =
173 "android.telecom.extra.SILENT_RINGING_REQUESTED";
174
Tyler Gunn8bf76572017-04-06 15:30:08 -0700175 /**
176 * Call event sent from a {@link Call} via {@link #sendCallEvent(String, Bundle)} to inform
177 * Telecom that the user has requested that the current {@link Call} should be handed over
178 * to another {@link ConnectionService}.
179 * <p>
180 * The caller must specify the {@link #EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE} to indicate to
181 * Telecom which {@link PhoneAccountHandle} the {@link Call} should be handed over to.
182 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700183 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
184 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700185 */
186 public static final String EVENT_REQUEST_HANDOVER =
187 "android.telecom.event.REQUEST_HANDOVER";
188
189 /**
190 * Extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Specifies the
191 * {@link PhoneAccountHandle} to which a call should be handed over to.
192 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700193 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
194 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700195 */
196 public static final String EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE =
197 "android.telecom.extra.HANDOVER_PHONE_ACCOUNT_HANDLE";
198
199 /**
200 * Integer extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Specifies the
201 * video state of the call when it is handed over to the new {@link PhoneAccount}.
202 * <p>
203 * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
204 * {@link VideoProfile#STATE_BIDIRECTIONAL}, {@link VideoProfile#STATE_RX_ENABLED}, and
205 * {@link VideoProfile#STATE_TX_ENABLED}.
206 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700207 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
208 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700209 */
210 public static final String EXTRA_HANDOVER_VIDEO_STATE =
211 "android.telecom.extra.HANDOVER_VIDEO_STATE";
212
213 /**
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700214 * Extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event. Used by the
215 * {@link InCallService} initiating a handover to provide a {@link Bundle} with extra
216 * information to the handover {@link ConnectionService} specified by
217 * {@link #EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE}.
218 * <p>
219 * This {@link Bundle} is not interpreted by Telecom, but passed as-is to the
220 * {@link ConnectionService} via the request extras when
221 * {@link ConnectionService#onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}
222 * is called to initate the handover.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700223 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700224 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
225 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700226 */
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700227 public static final String EXTRA_HANDOVER_EXTRAS = "android.telecom.extra.HANDOVER_EXTRAS";
Tyler Gunn8bf76572017-04-06 15:30:08 -0700228
229 /**
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700230 * Call event sent from Telecom to the handover {@link ConnectionService} via
231 * {@link Connection#onCallEvent(String, Bundle)} to inform a {@link Connection} that a handover
232 * to the {@link ConnectionService} has completed successfully.
233 * <p>
234 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700235 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700236 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
237 * APIs instead.
Tyler Gunn8bf76572017-04-06 15:30:08 -0700238 */
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700239 public static final String EVENT_HANDOVER_COMPLETE =
240 "android.telecom.event.HANDOVER_COMPLETE";
Tyler Gunn34a2b312017-06-23 08:32:00 -0700241
242 /**
243 * Call event sent from Telecom to the handover destination {@link ConnectionService} via
244 * {@link Connection#onCallEvent(String, Bundle)} to inform the handover destination that the
245 * source connection has disconnected. The {@link Bundle} parameter for the call event will be
246 * {@code null}.
247 * <p>
248 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
249 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700250 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
251 * APIs instead.
Tyler Gunn34a2b312017-06-23 08:32:00 -0700252 */
253 public static final String EVENT_HANDOVER_SOURCE_DISCONNECTED =
254 "android.telecom.event.HANDOVER_SOURCE_DISCONNECTED";
255
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700256 /**
257 * Call event sent from Telecom to the handover {@link ConnectionService} via
258 * {@link Connection#onCallEvent(String, Bundle)} to inform a {@link Connection} that a handover
259 * to the {@link ConnectionService} has failed.
260 * <p>
261 * A handover is initiated with the {@link #EVENT_REQUEST_HANDOVER} call event.
262 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700263 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
264 * APIs instead.
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700265 */
266 public static final String EVENT_HANDOVER_FAILED =
267 "android.telecom.event.HANDOVER_FAILED";
Tyler Gunn8bf76572017-04-06 15:30:08 -0700268
Ihab Awade63fadb2014-07-09 21:52:04 -0700269 public static class Details {
Tyler Gunn94f8f112018-12-17 09:56:11 -0800270 /** @hide */
271 @Retention(RetentionPolicy.SOURCE)
272 @IntDef(
273 prefix = { "DIRECTION_" },
274 value = {DIRECTION_UNKNOWN, DIRECTION_INCOMING, DIRECTION_OUTGOING})
275 public @interface CallDirection {}
276
277 /**
278 * Indicates that the call is neither and incoming nor an outgoing call. This can be the
279 * case for calls reported directly by a {@link ConnectionService} in special cases such as
280 * call handovers.
281 */
282 public static final int DIRECTION_UNKNOWN = -1;
283
284 /**
285 * Indicates that the call is an incoming call.
286 */
287 public static final int DIRECTION_INCOMING = 0;
288
289 /**
290 * Indicates that the call is an outgoing call.
291 */
292 public static final int DIRECTION_OUTGOING = 1;
293
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800294
295 /** Call can currently be put on hold or unheld. */
296 public static final int CAPABILITY_HOLD = 0x00000001;
297
298 /** Call supports the hold feature. */
299 public static final int CAPABILITY_SUPPORT_HOLD = 0x00000002;
300
301 /**
302 * Calls within a conference can be merged. A {@link ConnectionService} has the option to
303 * add a {@link Conference} call before the child {@link Connection}s are merged. This is how
304 * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this
305 * capability allows a merge button to be shown while the conference call is in the foreground
306 * of the in-call UI.
307 * <p>
308 * This is only intended for use by a {@link Conference}.
309 */
310 public static final int CAPABILITY_MERGE_CONFERENCE = 0x00000004;
311
312 /**
313 * Calls within a conference can be swapped between foreground and background.
314 * See {@link #CAPABILITY_MERGE_CONFERENCE} for additional information.
315 * <p>
316 * This is only intended for use by a {@link Conference}.
317 */
318 public static final int CAPABILITY_SWAP_CONFERENCE = 0x00000008;
319
320 /**
321 * @hide
322 */
Andrew Lee2378ea72015-04-29 14:38:11 -0700323 public static final int CAPABILITY_UNUSED_1 = 0x00000010;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800324
325 /** Call supports responding via text option. */
326 public static final int CAPABILITY_RESPOND_VIA_TEXT = 0x00000020;
327
328 /** Call can be muted. */
329 public static final int CAPABILITY_MUTE = 0x00000040;
330
331 /**
332 * Call supports conference call management. This capability only applies to {@link Conference}
333 * calls which can have {@link Connection}s as children.
334 */
335 public static final int CAPABILITY_MANAGE_CONFERENCE = 0x00000080;
336
337 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700338 * Local device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800339 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700340 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_RX = 0x00000100;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800341
342 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700343 * Local device supports transmitting video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800344 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700345 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_TX = 0x00000200;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800346
347 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700348 * Local device supports bidirectional video calling.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800349 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700350 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700351 CAPABILITY_SUPPORTS_VT_LOCAL_RX | CAPABILITY_SUPPORTS_VT_LOCAL_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800352
353 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700354 * Remote device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800355 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700356 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_RX = 0x00000400;
357
358 /**
359 * Remote device supports transmitting video.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700360 */
361 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_TX = 0x00000800;
362
363 /**
364 * Remote device supports bidirectional video calling.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700365 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700366 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700367 CAPABILITY_SUPPORTS_VT_REMOTE_RX | CAPABILITY_SUPPORTS_VT_REMOTE_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800368
369 /**
370 * Call is able to be separated from its parent {@code Conference}, if any.
371 */
372 public static final int CAPABILITY_SEPARATE_FROM_CONFERENCE = 0x00001000;
373
374 /**
375 * Call is able to be individually disconnected when in a {@code Conference}.
376 */
377 public static final int CAPABILITY_DISCONNECT_FROM_CONFERENCE = 0x00002000;
378
379 /**
Dong Zhou89f41eb2015-03-15 11:59:49 -0500380 * Speed up audio setup for MT call.
381 * @hide
382 */
Tyler Gunn96d6c402015-03-18 12:39:23 -0700383 public static final int CAPABILITY_SPEED_UP_MT_AUDIO = 0x00040000;
384
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700385 /**
386 * Call can be upgraded to a video call.
Rekha Kumar07366812015-03-24 16:42:31 -0700387 * @hide
Tyler Gunn6e3ecc42018-11-12 11:30:56 -0800388 * @deprecated Use {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
389 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL} to indicate for a call
390 * whether or not video calling is supported.
Rekha Kumar07366812015-03-24 16:42:31 -0700391 */
Tyler Gunn6e3ecc42018-11-12 11:30:56 -0800392 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 119305590)
Rekha Kumar07366812015-03-24 16:42:31 -0700393 public static final int CAPABILITY_CAN_UPGRADE_TO_VIDEO = 0x00080000;
394
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700395 /**
396 * For video calls, indicates whether the outgoing video for the call can be paused using
Yorke Lee32f24732015-05-12 16:18:03 -0700397 * the {@link android.telecom.VideoProfile#STATE_PAUSED} VideoState.
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700398 */
399 public static final int CAPABILITY_CAN_PAUSE_VIDEO = 0x00100000;
400
Bryce Lee81901682015-08-28 16:38:02 -0700401 /**
402 * Call sends responses through connection.
403 * @hide
404 */
Tyler Gunnf97a0092016-01-19 15:59:34 -0800405 public static final int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION = 0x00200000;
406
407 /**
408 * When set, prevents a video {@code Call} from being downgraded to an audio-only call.
409 * <p>
410 * Should be set when the VideoState has the {@link VideoProfile#STATE_TX_ENABLED} or
411 * {@link VideoProfile#STATE_RX_ENABLED} bits set to indicate that the connection cannot be
412 * downgraded from a video call back to a VideoState of
413 * {@link VideoProfile#STATE_AUDIO_ONLY}.
414 * <p>
415 * Intuitively, a call which can be downgraded to audio should also have local and remote
416 * video
417 * capabilities (see {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
418 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL}).
419 */
420 public static final int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO = 0x00400000;
Bryce Lee81901682015-08-28 16:38:02 -0700421
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700422 /**
423 * When set for an external call, indicates that this {@code Call} can be pulled from a
424 * remote device to the current device.
425 * <p>
426 * Should only be set on a {@code Call} where {@link #PROPERTY_IS_EXTERNAL_CALL} is set.
427 * <p>
428 * An {@link InCallService} will only see calls with this capability if it has the
429 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
430 * in its manifest.
431 * <p>
432 * See {@link Connection#CAPABILITY_CAN_PULL_CALL} and
Tyler Gunn720c6642016-03-22 09:02:47 -0700433 * {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700434 */
435 public static final int CAPABILITY_CAN_PULL_CALL = 0x00800000;
436
Pooja Jaind34698d2017-12-28 14:15:31 +0530437 /** Call supports the deflect feature. */
438 public static final int CAPABILITY_SUPPORT_DEFLECT = 0x01000000;
439
Tyler Gunnd11a3152015-03-18 13:09:14 -0700440 //******************************************************************************************
Pooja Jaind34698d2017-12-28 14:15:31 +0530441 // Next CAPABILITY value: 0x02000000
Andrew Lee2378ea72015-04-29 14:38:11 -0700442 //******************************************************************************************
443
444 /**
445 * Whether the call is currently a conference.
446 */
447 public static final int PROPERTY_CONFERENCE = 0x00000001;
448
449 /**
450 * Whether the call is a generic conference, where we do not know the precise state of
451 * participants in the conference (eg. on CDMA).
452 */
453 public static final int PROPERTY_GENERIC_CONFERENCE = 0x00000002;
454
455 /**
456 * Whether the call is made while the device is in emergency callback mode.
457 */
458 public static final int PROPERTY_EMERGENCY_CALLBACK_MODE = 0x00000004;
459
460 /**
461 * Connection is using WIFI.
462 */
463 public static final int PROPERTY_WIFI = 0x00000008;
464
465 /**
Tyler Gunn6b6ae552018-10-11 10:42:10 -0700466 * When set, the UI should indicate to the user that a call is using high definition
467 * audio.
468 * <p>
469 * The underlying {@link ConnectionService} is responsible for reporting this
470 * property. It is important to note that this property is not intended to report the
471 * actual audio codec being used for a Call, but whether the call should be indicated
472 * to the user as high definition.
473 * <p>
474 * The Android Telephony stack reports this property for calls based on a number
475 * of factors, including which audio codec is used and whether a call is using an HD
476 * codec end-to-end. Some mobile operators choose to suppress display of an HD indication,
477 * and in these cases this property will not be set for a call even if the underlying audio
478 * codec is in fact "high definition".
Andrew Lee2378ea72015-04-29 14:38:11 -0700479 */
480 public static final int PROPERTY_HIGH_DEF_AUDIO = 0x00000010;
481
Tony Maka68dcce2015-12-17 09:31:18 +0000482 /**
Tony Mak53b5df42016-05-19 13:40:38 +0100483 * Whether the call is associated with the work profile.
484 */
485 public static final int PROPERTY_ENTERPRISE_CALL = 0x00000020;
486
487 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700488 * When set, indicates that this {@code Call} does not actually exist locally for the
489 * {@link ConnectionService}.
490 * <p>
491 * Consider, for example, a scenario where a user has two phones with the same phone number.
492 * When a user places a call on one device, the telephony stack can represent that call on
493 * the other device by adding it to the {@link ConnectionService} with the
Tyler Gunn720c6642016-03-22 09:02:47 -0700494 * {@link Connection#PROPERTY_IS_EXTERNAL_CALL} property set.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700495 * <p>
496 * An {@link InCallService} will only see calls with this property if it has the
497 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
498 * in its manifest.
499 * <p>
Tyler Gunn720c6642016-03-22 09:02:47 -0700500 * See {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700501 */
502 public static final int PROPERTY_IS_EXTERNAL_CALL = 0x00000040;
503
Brad Ebinger15847072016-05-18 11:08:36 -0700504 /**
505 * Indicates that the call has CDMA Enhanced Voice Privacy enabled.
506 */
507 public static final int PROPERTY_HAS_CDMA_VOICE_PRIVACY = 0x00000080;
508
Tyler Gunn24e18332017-02-10 09:42:49 -0800509 /**
510 * Indicates that the call is from a self-managed {@link ConnectionService}.
511 * <p>
512 * See also {@link Connection#PROPERTY_SELF_MANAGED}
513 */
514 public static final int PROPERTY_SELF_MANAGED = 0x00000100;
515
Eric Erfanianec881872017-12-06 16:27:53 -0800516 /**
517 * Indicates the call used Assisted Dialing.
Tyler Gunn5567d742019-10-31 13:04:37 -0700518 *
519 * @see TelecomManager#EXTRA_USE_ASSISTED_DIALING
Eric Erfanianec881872017-12-06 16:27:53 -0800520 */
521 public static final int PROPERTY_ASSISTED_DIALING_USED = 0x00000200;
522
Hall Liue9041242018-02-09 16:40:03 -0800523 /**
524 * Indicates that the call is an RTT call. Use {@link #getRttCall()} to get the
525 * {@link RttCall} object that is used to send and receive text.
526 */
527 public static final int PROPERTY_RTT = 0x00000400;
528
Tyler Gunn5bd90852018-09-21 09:37:07 -0700529 /**
530 * Indicates that the call has been identified as the network as an emergency call. This
531 * property may be set for both incoming and outgoing calls which the network identifies as
532 * emergency calls.
533 */
534 public static final int PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL = 0x00000800;
535
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700536 /**
537 * Indicates that the call is using VoIP audio mode.
538 * <p>
539 * When this property is set, the {@link android.media.AudioManager} audio mode for this
540 * call will be {@link android.media.AudioManager#MODE_IN_COMMUNICATION}. When this
541 * property is not set, the audio mode for this call will be
542 * {@link android.media.AudioManager#MODE_IN_CALL}.
543 * <p>
544 * This property reflects changes made using {@link Connection#setAudioModeIsVoip(boolean)}.
545 * <p>
546 * You can use this property to determine whether an un-answered incoming call or a held
547 * call will use VoIP audio mode (if the call does not currently have focus, the system
548 * audio mode may not reflect the mode the call will use).
549 */
550 public static final int PROPERTY_VOIP_AUDIO_MODE = 0x00001000;
551
Andrew Lee2378ea72015-04-29 14:38:11 -0700552 //******************************************************************************************
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700553 // Next PROPERTY value: 0x00002000
Tyler Gunnd11a3152015-03-18 13:09:14 -0700554 //******************************************************************************************
Tyler Gunn068085b2015-02-06 13:56:52 -0800555
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800556 private final String mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -0700557 private final Uri mHandle;
558 private final int mHandlePresentation;
559 private final String mCallerDisplayName;
560 private final int mCallerDisplayNamePresentation;
Evan Charlton8c8a0622014-07-20 12:31:00 -0700561 private final PhoneAccountHandle mAccountHandle;
Ihab Awad5d0410f2014-07-30 10:07:40 -0700562 private final int mCallCapabilities;
Andrew Lee223ad142014-08-27 16:33:08 -0700563 private final int mCallProperties;
Christine Hallstrom4e22d6d2016-11-30 16:06:42 -0800564 private final int mSupportedAudioRoutes = CallAudioState.ROUTE_ALL;
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700565 private final DisconnectCause mDisconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -0700566 private final long mConnectTimeMillis;
567 private final GatewayInfo mGatewayInfo;
Andrew Lee85f5d422014-07-11 17:22:03 -0700568 private final int mVideoState;
Evan Charlton5b49ade2014-07-15 17:03:20 -0700569 private final StatusHints mStatusHints;
Nancy Chen10798dc2014-08-08 14:00:25 -0700570 private final Bundle mExtras;
Santos Cordon6b7f9552015-05-27 17:21:45 -0700571 private final Bundle mIntentExtras;
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700572 private final long mCreationTimeMillis;
Tyler Gunn94f8f112018-12-17 09:56:11 -0800573 private final @CallDirection int mCallDirection;
Ihab Awade63fadb2014-07-09 21:52:04 -0700574
575 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800576 * Whether the supplied capabilities supports the specified capability.
577 *
578 * @param capabilities A bit field of capabilities.
579 * @param capability The capability to check capabilities for.
580 * @return Whether the specified capability is supported.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800581 */
582 public static boolean can(int capabilities, int capability) {
Tyler Gunn014c7112015-12-18 14:33:57 -0800583 return (capabilities & capability) == capability;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800584 }
585
586 /**
587 * Whether the capabilities of this {@code Details} supports the specified capability.
588 *
589 * @param capability The capability to check capabilities for.
590 * @return Whether the specified capability is supported.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800591 */
592 public boolean can(int capability) {
593 return can(mCallCapabilities, capability);
594 }
595
596 /**
597 * Render a set of capability bits ({@code CAPABILITY_*}) as a human readable string.
598 *
599 * @param capabilities A capability bit field.
600 * @return A human readable string representation.
601 */
602 public static String capabilitiesToString(int capabilities) {
603 StringBuilder builder = new StringBuilder();
604 builder.append("[Capabilities:");
605 if (can(capabilities, CAPABILITY_HOLD)) {
606 builder.append(" CAPABILITY_HOLD");
607 }
608 if (can(capabilities, CAPABILITY_SUPPORT_HOLD)) {
609 builder.append(" CAPABILITY_SUPPORT_HOLD");
610 }
611 if (can(capabilities, CAPABILITY_MERGE_CONFERENCE)) {
612 builder.append(" CAPABILITY_MERGE_CONFERENCE");
613 }
614 if (can(capabilities, CAPABILITY_SWAP_CONFERENCE)) {
615 builder.append(" CAPABILITY_SWAP_CONFERENCE");
616 }
617 if (can(capabilities, CAPABILITY_RESPOND_VIA_TEXT)) {
618 builder.append(" CAPABILITY_RESPOND_VIA_TEXT");
619 }
620 if (can(capabilities, CAPABILITY_MUTE)) {
621 builder.append(" CAPABILITY_MUTE");
622 }
623 if (can(capabilities, CAPABILITY_MANAGE_CONFERENCE)) {
624 builder.append(" CAPABILITY_MANAGE_CONFERENCE");
625 }
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700626 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_RX)) {
627 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_RX");
628 }
629 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_TX)) {
630 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_TX");
631 }
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700632 if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL)) {
633 builder.append(" CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800634 }
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700635 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_RX)) {
636 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_RX");
637 }
638 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_TX)) {
639 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_TX");
640 }
Tyler Gunnf97a0092016-01-19 15:59:34 -0800641 if (can(capabilities, CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO)) {
642 builder.append(" CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO");
643 }
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700644 if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL)) {
645 builder.append(" CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800646 }
Dong Zhou89f41eb2015-03-15 11:59:49 -0500647 if (can(capabilities, CAPABILITY_SPEED_UP_MT_AUDIO)) {
Tyler Gunnd11a3152015-03-18 13:09:14 -0700648 builder.append(" CAPABILITY_SPEED_UP_MT_AUDIO");
Dong Zhou89f41eb2015-03-15 11:59:49 -0500649 }
Rekha Kumar07366812015-03-24 16:42:31 -0700650 if (can(capabilities, CAPABILITY_CAN_UPGRADE_TO_VIDEO)) {
651 builder.append(" CAPABILITY_CAN_UPGRADE_TO_VIDEO");
652 }
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700653 if (can(capabilities, CAPABILITY_CAN_PAUSE_VIDEO)) {
654 builder.append(" CAPABILITY_CAN_PAUSE_VIDEO");
655 }
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700656 if (can(capabilities, CAPABILITY_CAN_PULL_CALL)) {
657 builder.append(" CAPABILITY_CAN_PULL_CALL");
658 }
Pooja Jaind34698d2017-12-28 14:15:31 +0530659 if (can(capabilities, CAPABILITY_SUPPORT_DEFLECT)) {
660 builder.append(" CAPABILITY_SUPPORT_DEFLECT");
661 }
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800662 builder.append("]");
663 return builder.toString();
664 }
665
666 /**
Andrew Lee2378ea72015-04-29 14:38:11 -0700667 * Whether the supplied properties includes the specified property.
668 *
669 * @param properties A bit field of properties.
670 * @param property The property to check properties for.
671 * @return Whether the specified property is supported.
672 */
673 public static boolean hasProperty(int properties, int property) {
Tyler Gunn014c7112015-12-18 14:33:57 -0800674 return (properties & property) == property;
Andrew Lee2378ea72015-04-29 14:38:11 -0700675 }
676
677 /**
678 * Whether the properties of this {@code Details} includes the specified property.
679 *
680 * @param property The property to check properties for.
681 * @return Whether the specified property is supported.
682 */
683 public boolean hasProperty(int property) {
684 return hasProperty(mCallProperties, property);
685 }
686
687 /**
688 * Render a set of property bits ({@code PROPERTY_*}) as a human readable string.
689 *
690 * @param properties A property bit field.
691 * @return A human readable string representation.
692 */
693 public static String propertiesToString(int properties) {
694 StringBuilder builder = new StringBuilder();
695 builder.append("[Properties:");
696 if (hasProperty(properties, PROPERTY_CONFERENCE)) {
697 builder.append(" PROPERTY_CONFERENCE");
698 }
699 if (hasProperty(properties, PROPERTY_GENERIC_CONFERENCE)) {
700 builder.append(" PROPERTY_GENERIC_CONFERENCE");
701 }
702 if (hasProperty(properties, PROPERTY_WIFI)) {
703 builder.append(" PROPERTY_WIFI");
704 }
705 if (hasProperty(properties, PROPERTY_HIGH_DEF_AUDIO)) {
706 builder.append(" PROPERTY_HIGH_DEF_AUDIO");
707 }
708 if (hasProperty(properties, PROPERTY_EMERGENCY_CALLBACK_MODE)) {
Yorke Leebe2a4a22015-06-12 10:10:55 -0700709 builder.append(" PROPERTY_EMERGENCY_CALLBACK_MODE");
Andrew Lee2378ea72015-04-29 14:38:11 -0700710 }
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700711 if (hasProperty(properties, PROPERTY_IS_EXTERNAL_CALL)) {
712 builder.append(" PROPERTY_IS_EXTERNAL_CALL");
713 }
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700714 if (hasProperty(properties, PROPERTY_HAS_CDMA_VOICE_PRIVACY)) {
Brad Ebinger15847072016-05-18 11:08:36 -0700715 builder.append(" PROPERTY_HAS_CDMA_VOICE_PRIVACY");
716 }
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700717 if (hasProperty(properties, PROPERTY_ASSISTED_DIALING_USED)) {
Eric Erfanianec881872017-12-06 16:27:53 -0800718 builder.append(" PROPERTY_ASSISTED_DIALING_USED");
719 }
Tyler Gunn5bd90852018-09-21 09:37:07 -0700720 if (hasProperty(properties, PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL)) {
721 builder.append(" PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL");
722 }
Tyler Gunn80a5e1e2018-06-22 15:52:27 -0700723 if (hasProperty(properties, PROPERTY_RTT)) {
724 builder.append(" PROPERTY_RTT");
725 }
726 if (hasProperty(properties, PROPERTY_VOIP_AUDIO_MODE)) {
727 builder.append(" PROPERTY_VOIP_AUDIO_MODE");
728 }
Andrew Lee2378ea72015-04-29 14:38:11 -0700729 builder.append("]");
730 return builder.toString();
731 }
732
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800733 /** {@hide} */
Hall Liu31de23d2019-10-11 15:38:29 -0700734 @TestApi
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800735 public String getTelecomCallId() {
736 return mTelecomCallId;
737 }
738
Andrew Lee2378ea72015-04-29 14:38:11 -0700739 /**
Ihab Awade63fadb2014-07-09 21:52:04 -0700740 * @return The handle (e.g., phone number) to which the {@code Call} is currently
741 * connected.
742 */
743 public Uri getHandle() {
744 return mHandle;
745 }
746
747 /**
748 * @return The presentation requirements for the handle. See
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700749 * {@link TelecomManager} for valid values.
Ihab Awade63fadb2014-07-09 21:52:04 -0700750 */
751 public int getHandlePresentation() {
752 return mHandlePresentation;
753 }
754
755 /**
Tyler Gunnd081f042018-12-04 12:56:45 -0800756 * The display name for the caller.
757 * <p>
758 * This is the name as reported by the {@link ConnectionService} associated with this call.
Tyler Gunnd081f042018-12-04 12:56:45 -0800759 *
Ihab Awade63fadb2014-07-09 21:52:04 -0700760 * @return The display name for the caller.
761 */
762 public String getCallerDisplayName() {
763 return mCallerDisplayName;
764 }
765
766 /**
767 * @return The presentation requirements for the caller display name. See
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700768 * {@link TelecomManager} for valid values.
Ihab Awade63fadb2014-07-09 21:52:04 -0700769 */
770 public int getCallerDisplayNamePresentation() {
771 return mCallerDisplayNamePresentation;
772 }
773
774 /**
Evan Charlton6eb262c2014-07-19 18:18:19 -0700775 * @return The {@code PhoneAccountHandle} whereby the {@code Call} is currently being
776 * routed.
Ihab Awade63fadb2014-07-09 21:52:04 -0700777 */
Evan Charlton8c8a0622014-07-20 12:31:00 -0700778 public PhoneAccountHandle getAccountHandle() {
779 return mAccountHandle;
Ihab Awade63fadb2014-07-09 21:52:04 -0700780 }
781
782 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800783 * @return A bitmask of the capabilities of the {@code Call}, as defined by the various
784 * {@code CAPABILITY_*} constants in this class.
Ihab Awade63fadb2014-07-09 21:52:04 -0700785 */
Ihab Awad5d0410f2014-07-30 10:07:40 -0700786 public int getCallCapabilities() {
787 return mCallCapabilities;
Ihab Awade63fadb2014-07-09 21:52:04 -0700788 }
789
790 /**
Andrew Lee2378ea72015-04-29 14:38:11 -0700791 * @return A bitmask of the properties of the {@code Call}, as defined by the various
792 * {@code PROPERTY_*} constants in this class.
Andrew Lee223ad142014-08-27 16:33:08 -0700793 */
794 public int getCallProperties() {
795 return mCallProperties;
796 }
797
798 /**
Christine Hallstrom4e22d6d2016-11-30 16:06:42 -0800799 * @return a bitmask of the audio routes available for the call.
800 *
801 * @hide
802 */
803 public int getSupportedAudioRoutes() {
804 return mSupportedAudioRoutes;
805 }
806
807 /**
Ihab Awade63fadb2014-07-09 21:52:04 -0700808 * @return For a {@link #STATE_DISCONNECTED} {@code Call}, the disconnect cause expressed
Nancy Chenf4cf77c2014-09-19 10:53:21 -0700809 * by {@link android.telecom.DisconnectCause}.
Ihab Awade63fadb2014-07-09 21:52:04 -0700810 */
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700811 public DisconnectCause getDisconnectCause() {
812 return mDisconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -0700813 }
814
815 /**
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700816 * Returns the time the {@link Call} connected (i.e. became active). This information is
817 * updated periodically, but user interfaces should not rely on this to display the "call
818 * time clock". For the time when the call was first added to Telecom, see
819 * {@link #getCreationTimeMillis()}.
820 *
821 * @return The time the {@link Call} connected in milliseconds since the epoch.
Ihab Awade63fadb2014-07-09 21:52:04 -0700822 */
Jay Shrauner164a0ac2015-04-14 18:16:10 -0700823 public final long getConnectTimeMillis() {
Ihab Awade63fadb2014-07-09 21:52:04 -0700824 return mConnectTimeMillis;
825 }
826
827 /**
828 * @return Information about any calling gateway the {@code Call} may be using.
829 */
830 public GatewayInfo getGatewayInfo() {
831 return mGatewayInfo;
832 }
833
Andrew Lee7a341382014-07-15 17:05:08 -0700834 /**
Ihab Awad5d0410f2014-07-30 10:07:40 -0700835 * @return The video state of the {@code Call}.
Andrew Lee7a341382014-07-15 17:05:08 -0700836 */
837 public int getVideoState() {
838 return mVideoState;
839 }
840
Ihab Awad5d0410f2014-07-30 10:07:40 -0700841 /**
Tyler Gunnef9f6f92014-09-12 22:16:17 -0700842 * @return The current {@link android.telecom.StatusHints}, or {@code null} if none
Ihab Awad5d0410f2014-07-30 10:07:40 -0700843 * have been set.
Evan Charlton5b49ade2014-07-15 17:03:20 -0700844 */
845 public StatusHints getStatusHints() {
846 return mStatusHints;
847 }
848
Nancy Chen10798dc2014-08-08 14:00:25 -0700849 /**
Santos Cordon6b7f9552015-05-27 17:21:45 -0700850 * @return The extras associated with this call.
Nancy Chen10798dc2014-08-08 14:00:25 -0700851 */
852 public Bundle getExtras() {
853 return mExtras;
854 }
855
Santos Cordon6b7f9552015-05-27 17:21:45 -0700856 /**
857 * @return The extras used with the original intent to place this call.
858 */
859 public Bundle getIntentExtras() {
860 return mIntentExtras;
861 }
862
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700863 /**
864 * Returns the time when the call was first created and added to Telecom. This is the same
865 * time that is logged as the start time in the Call Log (see
866 * {@link android.provider.CallLog.Calls#DATE}). To determine when the call was connected
867 * (became active), see {@link #getConnectTimeMillis()}.
868 *
869 * @return The creation time of the call, in millis since the epoch.
870 */
871 public long getCreationTimeMillis() {
872 return mCreationTimeMillis;
873 }
874
Tyler Gunnd081f042018-12-04 12:56:45 -0800875 /**
Tyler Gunn94f8f112018-12-17 09:56:11 -0800876 * Indicates whether the call is an incoming or outgoing call.
877 * @return The call's direction.
878 */
879 public @CallDirection int getCallDirection() {
880 return mCallDirection;
881 }
882
Ihab Awade63fadb2014-07-09 21:52:04 -0700883 @Override
884 public boolean equals(Object o) {
885 if (o instanceof Details) {
886 Details d = (Details) o;
887 return
888 Objects.equals(mHandle, d.mHandle) &&
889 Objects.equals(mHandlePresentation, d.mHandlePresentation) &&
890 Objects.equals(mCallerDisplayName, d.mCallerDisplayName) &&
891 Objects.equals(mCallerDisplayNamePresentation,
892 d.mCallerDisplayNamePresentation) &&
Evan Charlton8c8a0622014-07-20 12:31:00 -0700893 Objects.equals(mAccountHandle, d.mAccountHandle) &&
Ihab Awad5d0410f2014-07-30 10:07:40 -0700894 Objects.equals(mCallCapabilities, d.mCallCapabilities) &&
Andrew Lee223ad142014-08-27 16:33:08 -0700895 Objects.equals(mCallProperties, d.mCallProperties) &&
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700896 Objects.equals(mDisconnectCause, d.mDisconnectCause) &&
Ihab Awade63fadb2014-07-09 21:52:04 -0700897 Objects.equals(mConnectTimeMillis, d.mConnectTimeMillis) &&
Andrew Lee85f5d422014-07-11 17:22:03 -0700898 Objects.equals(mGatewayInfo, d.mGatewayInfo) &&
Evan Charlton5b49ade2014-07-15 17:03:20 -0700899 Objects.equals(mVideoState, d.mVideoState) &&
Nancy Chen10798dc2014-08-08 14:00:25 -0700900 Objects.equals(mStatusHints, d.mStatusHints) &&
Tyler Gunn1e9bfc62015-08-19 11:18:58 -0700901 areBundlesEqual(mExtras, d.mExtras) &&
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700902 areBundlesEqual(mIntentExtras, d.mIntentExtras) &&
Tyler Gunnd081f042018-12-04 12:56:45 -0800903 Objects.equals(mCreationTimeMillis, d.mCreationTimeMillis) &&
Tyler Gunn94f8f112018-12-17 09:56:11 -0800904 Objects.equals(mCallDirection, d.mCallDirection);
Ihab Awade63fadb2014-07-09 21:52:04 -0700905 }
906 return false;
907 }
908
909 @Override
910 public int hashCode() {
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700911 return Objects.hash(mHandle,
912 mHandlePresentation,
913 mCallerDisplayName,
914 mCallerDisplayNamePresentation,
915 mAccountHandle,
916 mCallCapabilities,
917 mCallProperties,
918 mDisconnectCause,
919 mConnectTimeMillis,
920 mGatewayInfo,
921 mVideoState,
922 mStatusHints,
923 mExtras,
924 mIntentExtras,
Tyler Gunnd081f042018-12-04 12:56:45 -0800925 mCreationTimeMillis,
Tyler Gunn94f8f112018-12-17 09:56:11 -0800926 mCallDirection);
Ihab Awade63fadb2014-07-09 21:52:04 -0700927 }
928
929 /** {@hide} */
930 public Details(
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800931 String telecomCallId,
Ihab Awade63fadb2014-07-09 21:52:04 -0700932 Uri handle,
933 int handlePresentation,
934 String callerDisplayName,
935 int callerDisplayNamePresentation,
Evan Charlton8c8a0622014-07-20 12:31:00 -0700936 PhoneAccountHandle accountHandle,
Ihab Awade63fadb2014-07-09 21:52:04 -0700937 int capabilities,
Andrew Lee223ad142014-08-27 16:33:08 -0700938 int properties,
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700939 DisconnectCause disconnectCause,
Ihab Awade63fadb2014-07-09 21:52:04 -0700940 long connectTimeMillis,
Andrew Lee85f5d422014-07-11 17:22:03 -0700941 GatewayInfo gatewayInfo,
Evan Charlton5b49ade2014-07-15 17:03:20 -0700942 int videoState,
Nancy Chen10798dc2014-08-08 14:00:25 -0700943 StatusHints statusHints,
Santos Cordon6b7f9552015-05-27 17:21:45 -0700944 Bundle extras,
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700945 Bundle intentExtras,
Tyler Gunnd081f042018-12-04 12:56:45 -0800946 long creationTimeMillis,
Tyler Gunn94f8f112018-12-17 09:56:11 -0800947 int callDirection) {
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800948 mTelecomCallId = telecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -0700949 mHandle = handle;
950 mHandlePresentation = handlePresentation;
951 mCallerDisplayName = callerDisplayName;
952 mCallerDisplayNamePresentation = callerDisplayNamePresentation;
Evan Charlton8c8a0622014-07-20 12:31:00 -0700953 mAccountHandle = accountHandle;
Ihab Awad5d0410f2014-07-30 10:07:40 -0700954 mCallCapabilities = capabilities;
Andrew Lee223ad142014-08-27 16:33:08 -0700955 mCallProperties = properties;
Andrew Lee7f3d41f2014-09-11 17:33:16 -0700956 mDisconnectCause = disconnectCause;
Ihab Awade63fadb2014-07-09 21:52:04 -0700957 mConnectTimeMillis = connectTimeMillis;
958 mGatewayInfo = gatewayInfo;
Andrew Lee85f5d422014-07-11 17:22:03 -0700959 mVideoState = videoState;
Evan Charlton5b49ade2014-07-15 17:03:20 -0700960 mStatusHints = statusHints;
Nancy Chen10798dc2014-08-08 14:00:25 -0700961 mExtras = extras;
Santos Cordon6b7f9552015-05-27 17:21:45 -0700962 mIntentExtras = intentExtras;
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700963 mCreationTimeMillis = creationTimeMillis;
Tyler Gunn94f8f112018-12-17 09:56:11 -0800964 mCallDirection = callDirection;
Ihab Awade63fadb2014-07-09 21:52:04 -0700965 }
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800966
967 /** {@hide} */
968 public static Details createFromParcelableCall(ParcelableCall parcelableCall) {
969 return new Details(
970 parcelableCall.getId(),
971 parcelableCall.getHandle(),
972 parcelableCall.getHandlePresentation(),
973 parcelableCall.getCallerDisplayName(),
974 parcelableCall.getCallerDisplayNamePresentation(),
975 parcelableCall.getAccountHandle(),
976 parcelableCall.getCapabilities(),
977 parcelableCall.getProperties(),
978 parcelableCall.getDisconnectCause(),
979 parcelableCall.getConnectTimeMillis(),
980 parcelableCall.getGatewayInfo(),
981 parcelableCall.getVideoState(),
982 parcelableCall.getStatusHints(),
983 parcelableCall.getExtras(),
Tyler Gunnc0bf6de2017-03-17 11:27:09 -0700984 parcelableCall.getIntentExtras(),
Tyler Gunnd081f042018-12-04 12:56:45 -0800985 parcelableCall.getCreationTimeMillis(),
Tyler Gunn94f8f112018-12-17 09:56:11 -0800986 parcelableCall.getCallDirection());
Sailesh Nepal1bef3392016-01-24 18:21:53 -0800987 }
Santos Cordon3c20d632016-02-25 16:12:35 -0800988
989 @Override
990 public String toString() {
991 StringBuilder sb = new StringBuilder();
Tyler Gunn3cd820f2018-11-30 14:21:18 -0800992 sb.append("[id: ");
993 sb.append(mTelecomCallId);
994 sb.append(", pa: ");
Santos Cordon3c20d632016-02-25 16:12:35 -0800995 sb.append(mAccountHandle);
996 sb.append(", hdl: ");
Tyler Gunn3cd820f2018-11-30 14:21:18 -0800997 sb.append(Log.piiHandle(mHandle));
998 sb.append(", hdlPres: ");
999 sb.append(mHandlePresentation);
1000 sb.append(", videoState: ");
1001 sb.append(VideoProfile.videoStateToString(mVideoState));
Santos Cordon3c20d632016-02-25 16:12:35 -08001002 sb.append(", caps: ");
1003 sb.append(capabilitiesToString(mCallCapabilities));
1004 sb.append(", props: ");
Tyler Gunn720c6642016-03-22 09:02:47 -07001005 sb.append(propertiesToString(mCallProperties));
Santos Cordon3c20d632016-02-25 16:12:35 -08001006 sb.append("]");
1007 return sb.toString();
1008 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001009 }
1010
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001011 /**
1012 * Defines callbacks which inform the {@link InCallService} of changes to a {@link Call}.
1013 * These callbacks can originate from the Telecom framework, or a {@link ConnectionService}
1014 * implementation.
1015 * <p>
1016 * You can handle these callbacks by extending the {@link Callback} class and overriding the
1017 * callbacks that your {@link InCallService} is interested in. The callback methods include the
1018 * {@link Call} for which the callback applies, allowing reuse of a single instance of your
1019 * {@link Callback} implementation, if desired.
1020 * <p>
1021 * Use {@link Call#registerCallback(Callback)} to register your callback(s). Ensure
1022 * {@link Call#unregisterCallback(Callback)} is called when you no longer require callbacks
1023 * (typically in {@link InCallService#onCallRemoved(Call)}).
1024 * Note: Callbacks which occur before you call {@link Call#registerCallback(Callback)} will not
1025 * reach your implementation of {@link Callback}, so it is important to register your callback
1026 * as soon as your {@link InCallService} is notified of a new call via
1027 * {@link InCallService#onCallAdded(Call)}.
1028 */
Andrew Leeda80c872015-04-15 14:09:50 -07001029 public static abstract class Callback {
Ihab Awade63fadb2014-07-09 21:52:04 -07001030 /**
Sanket Padawea8eddd42017-11-03 11:07:35 -07001031 * @hide
1032 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001033 @IntDef(prefix = { "HANDOVER_" },
1034 value = {HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_NOT_SUPPORTED,
Tyler Gunn5c60d712018-03-16 09:53:44 -07001035 HANDOVER_FAILURE_USER_REJECTED, HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL,
Tyler Gunn9d127732018-03-02 15:45:51 -08001036 HANDOVER_FAILURE_UNKNOWN})
Sanket Padawea8eddd42017-11-03 11:07:35 -07001037 @Retention(RetentionPolicy.SOURCE)
1038 public @interface HandoverFailureErrors {}
1039
1040 /**
1041 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the app
Tyler Gunn9d127732018-03-02 15:45:51 -08001042 * to handover the call to rejects the handover request.
1043 * <p>
1044 * Will be returned when {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} is called
1045 * and the destination {@link PhoneAccountHandle}'s {@link ConnectionService} returns a
1046 * {@code null} {@link Connection} from
1047 * {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
1048 * ConnectionRequest)}.
1049 * <p>
1050 * For more information on call handovers, see
1051 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001052 */
1053 public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1;
1054
1055 /**
Tyler Gunn9d127732018-03-02 15:45:51 -08001056 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
1057 * is initiated but the source or destination app does not support handover.
1058 * <p>
1059 * Will be returned when a handover is requested via
1060 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)} and the destination
1061 * {@link PhoneAccountHandle} does not declare
1062 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}. May also be returned when a handover is
1063 * requested at the {@link PhoneAccountHandle} for the current call (i.e. the source call's
1064 * {@link Details#getAccountHandle()}) does not declare
1065 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}.
1066 * <p>
1067 * For more information on call handovers, see
1068 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001069 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001070 public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001071
1072 /**
Tyler Gunn9d127732018-03-02 15:45:51 -08001073 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the remote
1074 * user rejects the handover request.
1075 * <p>
1076 * For more information on call handovers, see
1077 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001078 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001079 public static final int HANDOVER_FAILURE_USER_REJECTED = 3;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001080
Sanket Padawe85291f62017-12-01 13:59:27 -08001081 /**
1082 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there
1083 * is ongoing emergency call.
Tyler Gunn9d127732018-03-02 15:45:51 -08001084 * <p>
1085 * This error code is returned when {@link #handoverTo(PhoneAccountHandle, int, Bundle)} is
1086 * called on an emergency call, or if any other call is an emergency call.
1087 * <p>
1088 * Handovers are not permitted while there are ongoing emergency calls.
1089 * <p>
1090 * For more information on call handovers, see
1091 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
Sanket Padawe85291f62017-12-01 13:59:27 -08001092 */
Tyler Gunn5c60d712018-03-16 09:53:44 -07001093 public static final int HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL = 4;
Sanket Padawe85291f62017-12-01 13:59:27 -08001094
Tyler Gunn9d127732018-03-02 15:45:51 -08001095 /**
1096 * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
1097 * fails for an unknown reason.
1098 * <p>
1099 * For more information on call handovers, see
1100 * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
1101 */
1102 public static final int HANDOVER_FAILURE_UNKNOWN = 5;
Sanket Padawea8eddd42017-11-03 11:07:35 -07001103
1104 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001105 * Invoked when the state of this {@code Call} has changed. See {@link #getState()}.
1106 *
Ihab Awade63fadb2014-07-09 21:52:04 -07001107 * @param call The {@code Call} invoking this method.
1108 * @param state The new state of the {@code Call}.
1109 */
1110 public void onStateChanged(Call call, int state) {}
1111
1112 /**
1113 * Invoked when the parent of this {@code Call} has changed. See {@link #getParent()}.
1114 *
1115 * @param call The {@code Call} invoking this method.
1116 * @param parent The new parent of the {@code Call}.
1117 */
1118 public void onParentChanged(Call call, Call parent) {}
1119
1120 /**
1121 * Invoked when the children of this {@code Call} have changed. See {@link #getChildren()}.
1122 *
1123 * @param call The {@code Call} invoking this method.
1124 * @param children The new children of the {@code Call}.
1125 */
1126 public void onChildrenChanged(Call call, List<Call> children) {}
1127
1128 /**
1129 * Invoked when the details of this {@code Call} have changed. See {@link #getDetails()}.
1130 *
1131 * @param call The {@code Call} invoking this method.
1132 * @param details A {@code Details} object describing the {@code Call}.
1133 */
1134 public void onDetailsChanged(Call call, Details details) {}
1135
1136 /**
1137 * Invoked when the text messages that can be used as responses to the incoming
1138 * {@code Call} are loaded from the relevant database.
1139 * See {@link #getCannedTextResponses()}.
1140 *
1141 * @param call The {@code Call} invoking this method.
1142 * @param cannedTextResponses The text messages useable as responses.
1143 */
1144 public void onCannedTextResponsesLoaded(Call call, List<String> cannedTextResponses) {}
1145
1146 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001147 * Invoked when the post-dial sequence in the outgoing {@code Call} has reached a pause
1148 * character. This causes the post-dial signals to stop pending user confirmation. An
1149 * implementation should present this choice to the user and invoke
1150 * {@link #postDialContinue(boolean)} when the user makes the choice.
1151 *
1152 * @param call The {@code Call} invoking this method.
1153 * @param remainingPostDialSequence The post-dial characters that remain to be sent.
1154 */
1155 public void onPostDialWait(Call call, String remainingPostDialSequence) {}
1156
1157 /**
Andrew Lee50aca232014-07-22 16:41:54 -07001158 * Invoked when the {@code Call.VideoCall} of the {@code Call} has changed.
Ihab Awade63fadb2014-07-09 21:52:04 -07001159 *
1160 * @param call The {@code Call} invoking this method.
Andrew Lee50aca232014-07-22 16:41:54 -07001161 * @param videoCall The {@code Call.VideoCall} associated with the {@code Call}.
Ihab Awade63fadb2014-07-09 21:52:04 -07001162 */
Andrew Lee50aca232014-07-22 16:41:54 -07001163 public void onVideoCallChanged(Call call, InCallService.VideoCall videoCall) {}
Ihab Awade63fadb2014-07-09 21:52:04 -07001164
1165 /**
1166 * Invoked when the {@code Call} is destroyed. Clients should refrain from cleaning
1167 * up their UI for the {@code Call} in response to state transitions. Specifically,
1168 * clients should not assume that a {@link #onStateChanged(Call, int)} with a state of
1169 * {@link #STATE_DISCONNECTED} is the final notification the {@code Call} will send. Rather,
1170 * clients should wait for this method to be invoked.
1171 *
1172 * @param call The {@code Call} being destroyed.
1173 */
1174 public void onCallDestroyed(Call call) {}
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001175
1176 /**
1177 * Invoked upon changes to the set of {@code Call}s with which this {@code Call} can be
1178 * conferenced.
1179 *
1180 * @param call The {@code Call} being updated.
1181 * @param conferenceableCalls The {@code Call}s with which this {@code Call} can be
1182 * conferenced.
1183 */
1184 public void onConferenceableCallsChanged(Call call, List<Call> conferenceableCalls) {}
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001185
1186 /**
Tyler Gunn5567d742019-10-31 13:04:37 -07001187 * Invoked when a {@link Call} receives an event from its associated {@link Connection} or
1188 * {@link Conference}.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001189 * <p>
1190 * Where possible, the Call should make an attempt to handle {@link Connection} events which
1191 * are part of the {@code android.telecom.*} namespace. The Call should ignore any events
1192 * it does not wish to handle. Unexpected events should be handled gracefully, as it is
1193 * possible that a {@link ConnectionService} has defined its own Connection events which a
1194 * Call is not aware of.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001195 * <p>
Tyler Gunn5567d742019-10-31 13:04:37 -07001196 * See {@link Connection#sendConnectionEvent(String, Bundle)},
1197 * {@link Conference#sendConferenceEvent(String, Bundle)}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001198 *
1199 * @param call The {@code Call} receiving the event.
1200 * @param event The event.
1201 * @param extras Extras associated with the connection event.
1202 */
1203 public void onConnectionEvent(Call call, String event, Bundle extras) {}
Hall Liu95d55872017-01-25 17:12:49 -08001204
1205 /**
1206 * Invoked when the RTT mode changes for this call.
1207 * @param call The call whose RTT mode has changed.
1208 * @param mode the new RTT mode, one of
1209 * {@link RttCall#RTT_MODE_FULL}, {@link RttCall#RTT_MODE_HCO},
1210 * or {@link RttCall#RTT_MODE_VCO}
1211 */
1212 public void onRttModeChanged(Call call, int mode) {}
1213
1214 /**
1215 * Invoked when the call's RTT status changes, either from off to on or from on to off.
1216 * @param call The call whose RTT status has changed.
1217 * @param enabled whether RTT is now enabled or disabled
1218 * @param rttCall the {@link RttCall} object to use for reading and writing if RTT is now
1219 * on, null otherwise.
1220 */
1221 public void onRttStatusChanged(Call call, boolean enabled, RttCall rttCall) {}
1222
1223 /**
1224 * Invoked when the remote end of the connection has requested that an RTT communication
1225 * channel be opened. A response to this should be sent via {@link #respondToRttRequest}
1226 * with the same ID that this method is invoked with.
1227 * @param call The call which the RTT request was placed on
1228 * @param id The ID of the request.
1229 */
1230 public void onRttRequest(Call call, int id) {}
Hall Liu57006aa2017-02-06 10:49:48 -08001231
1232 /**
1233 * Invoked when the RTT session failed to initiate for some reason, including rejection
1234 * by the remote party.
1235 * @param call The call which the RTT initiation failure occurred on.
1236 * @param reason One of the status codes defined in
1237 * {@link android.telecom.Connection.RttModifyStatus}, with the exception of
1238 * {@link android.telecom.Connection.RttModifyStatus#SESSION_MODIFY_REQUEST_SUCCESS}.
1239 */
1240 public void onRttInitiationFailure(Call call, int reason) {}
Sanket Padawea8eddd42017-11-03 11:07:35 -07001241
1242 /**
1243 * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
1244 * has completed successfully.
Tyler Gunn9d127732018-03-02 15:45:51 -08001245 * <p>
1246 * For a full discussion of the handover process and the APIs involved, see
1247 * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
1248 *
Sanket Padawea8eddd42017-11-03 11:07:35 -07001249 * @param call The call which had initiated handover.
1250 */
1251 public void onHandoverComplete(Call call) {}
1252
1253 /**
1254 * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
1255 * has failed.
Tyler Gunn9d127732018-03-02 15:45:51 -08001256 * <p>
1257 * For a full discussion of the handover process and the APIs involved, see
1258 * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
1259 *
Sanket Padawea8eddd42017-11-03 11:07:35 -07001260 * @param call The call which had initiated handover.
Tyler Gunn9d127732018-03-02 15:45:51 -08001261 * @param failureReason Error reason for failure.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001262 */
1263 public void onHandoverFailed(Call call, @HandoverFailureErrors int failureReason) {}
Hall Liu95d55872017-01-25 17:12:49 -08001264 }
1265
1266 /**
1267 * A class that holds the state that describes the state of the RTT channel to the remote
1268 * party, if it is active.
1269 */
1270 public static final class RttCall {
Hall Liu07094df2017-02-28 15:17:44 -08001271 /** @hide */
Hall Liu95d55872017-01-25 17:12:49 -08001272 @Retention(RetentionPolicy.SOURCE)
1273 @IntDef({RTT_MODE_INVALID, RTT_MODE_FULL, RTT_MODE_HCO, RTT_MODE_VCO})
1274 public @interface RttAudioMode {}
1275
1276 /**
1277 * For metrics use. Default value in the proto.
1278 * @hide
1279 */
1280 public static final int RTT_MODE_INVALID = 0;
1281
1282 /**
1283 * Indicates that there should be a bidirectional audio stream between the two parties
1284 * on the call.
1285 */
1286 public static final int RTT_MODE_FULL = 1;
1287
1288 /**
1289 * Indicates that the local user should be able to hear the audio stream from the remote
1290 * user, but not vice versa. Equivalent to muting the microphone.
1291 */
1292 public static final int RTT_MODE_HCO = 2;
1293
1294 /**
1295 * Indicates that the remote user should be able to hear the audio stream from the local
1296 * user, but not vice versa. Equivalent to setting the volume to zero.
1297 */
1298 public static final int RTT_MODE_VCO = 3;
1299
1300 private static final int READ_BUFFER_SIZE = 1000;
1301
1302 private InputStreamReader mReceiveStream;
1303 private OutputStreamWriter mTransmitStream;
1304 private int mRttMode;
1305 private final InCallAdapter mInCallAdapter;
Hall Liu57006aa2017-02-06 10:49:48 -08001306 private final String mTelecomCallId;
Hall Liu95d55872017-01-25 17:12:49 -08001307 private char[] mReadBuffer = new char[READ_BUFFER_SIZE];
1308
1309 /**
1310 * @hide
1311 */
Hall Liu57006aa2017-02-06 10:49:48 -08001312 public RttCall(String telecomCallId, InputStreamReader receiveStream,
1313 OutputStreamWriter transmitStream, int mode, InCallAdapter inCallAdapter) {
1314 mTelecomCallId = telecomCallId;
Hall Liu95d55872017-01-25 17:12:49 -08001315 mReceiveStream = receiveStream;
1316 mTransmitStream = transmitStream;
1317 mRttMode = mode;
1318 mInCallAdapter = inCallAdapter;
1319 }
1320
1321 /**
1322 * Returns the current RTT audio mode.
1323 * @return Current RTT audio mode. One of {@link #RTT_MODE_FULL}, {@link #RTT_MODE_VCO}, or
1324 * {@link #RTT_MODE_HCO}.
1325 */
1326 public int getRttAudioMode() {
1327 return mRttMode;
1328 }
1329
1330 /**
1331 * Sets the RTT audio mode. The requested mode change will be communicated through
1332 * {@link Callback#onRttModeChanged(Call, int)}.
1333 * @param mode The desired RTT audio mode, one of {@link #RTT_MODE_FULL},
1334 * {@link #RTT_MODE_VCO}, or {@link #RTT_MODE_HCO}.
1335 */
1336 public void setRttMode(@RttAudioMode int mode) {
Hall Liu57006aa2017-02-06 10:49:48 -08001337 mInCallAdapter.setRttMode(mTelecomCallId, mode);
Hall Liu95d55872017-01-25 17:12:49 -08001338 }
1339
1340 /**
1341 * Writes the string {@param input} into the outgoing text stream for this RTT call. Since
1342 * RTT transmits text in real-time, this method should be called once for each character
1343 * the user enters into the device.
1344 *
1345 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1346 * lead to interleaved text.
1347 * @param input The message to send to the remote user.
1348 */
1349 public void write(String input) throws IOException {
1350 mTransmitStream.write(input);
1351 mTransmitStream.flush();
1352 }
1353
1354 /**
1355 * Reads a string from the remote user, blocking if there is no data available. Returns
1356 * {@code null} if the RTT conversation has been terminated and there is no further data
1357 * to read.
1358 *
1359 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1360 * lead to interleaved text.
1361 * @return A string containing text sent by the remote user, or {@code null} if the
1362 * conversation has been terminated or if there was an error while reading.
1363 */
Hall Liub1c8a772017-07-17 17:04:41 -07001364 public String read() {
1365 try {
1366 int numRead = mReceiveStream.read(mReadBuffer, 0, READ_BUFFER_SIZE);
1367 if (numRead < 0) {
1368 return null;
1369 }
1370 return new String(mReadBuffer, 0, numRead);
1371 } catch (IOException e) {
1372 Log.w(this, "Exception encountered when reading from InputStreamReader: %s", e);
Jeff Sharkey90396362017-06-12 16:26:53 -06001373 return null;
Hall Liuffa4a812017-03-02 16:11:00 -08001374 }
Hall Liuffa4a812017-03-02 16:11:00 -08001375 }
1376
1377 /**
1378 * Non-blocking version of {@link #read()}. Returns {@code null} if there is nothing to
1379 * be read.
1380 * @return A string containing text entered by the user, or {@code null} if the user has
1381 * not entered any new text yet.
1382 */
1383 public String readImmediately() throws IOException {
1384 if (mReceiveStream.ready()) {
Hall Liub1c8a772017-07-17 17:04:41 -07001385 int numRead = mReceiveStream.read(mReadBuffer, 0, READ_BUFFER_SIZE);
1386 if (numRead < 0) {
1387 return null;
1388 }
1389 return new String(mReadBuffer, 0, numRead);
Hall Liuffa4a812017-03-02 16:11:00 -08001390 } else {
Hall Liu95d55872017-01-25 17:12:49 -08001391 return null;
1392 }
1393 }
Hall Liue9041242018-02-09 16:40:03 -08001394
1395 /**
1396 * Closes the underlying file descriptors
1397 * @hide
1398 */
1399 public void close() {
1400 try {
1401 mReceiveStream.close();
1402 } catch (IOException e) {
1403 // ignore
1404 }
1405 try {
1406 mTransmitStream.close();
1407 } catch (IOException e) {
1408 // ignore
1409 }
1410 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001411 }
1412
Andrew Leeda80c872015-04-15 14:09:50 -07001413 /**
1414 * @deprecated Use {@code Call.Callback} instead.
1415 * @hide
1416 */
1417 @Deprecated
1418 @SystemApi
1419 public static abstract class Listener extends Callback { }
1420
Ihab Awade63fadb2014-07-09 21:52:04 -07001421 private final Phone mPhone;
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001422 private final String mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07001423 private final InCallAdapter mInCallAdapter;
Santos Cordon823fd3c2014-08-07 18:35:18 -07001424 private final List<String> mChildrenIds = new ArrayList<>();
Ihab Awade63fadb2014-07-09 21:52:04 -07001425 private final List<Call> mChildren = new ArrayList<>();
1426 private final List<Call> mUnmodifiableChildren = Collections.unmodifiableList(mChildren);
Andrew Lee011728f2015-04-23 15:47:06 -07001427 private final List<CallbackRecord<Callback>> mCallbackRecords = new CopyOnWriteArrayList<>();
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001428 private final List<Call> mConferenceableCalls = new ArrayList<>();
1429 private final List<Call> mUnmodifiableConferenceableCalls =
1430 Collections.unmodifiableList(mConferenceableCalls);
1431
Santos Cordon823fd3c2014-08-07 18:35:18 -07001432 private boolean mChildrenCached;
1433 private String mParentId = null;
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001434 private int mState;
Ihab Awade63fadb2014-07-09 21:52:04 -07001435 private List<String> mCannedTextResponses = null;
Tyler Gunnb88b3112016-11-09 10:19:23 -08001436 private String mCallingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08001437 private int mTargetSdkVersion;
Ihab Awade63fadb2014-07-09 21:52:04 -07001438 private String mRemainingPostDialSequence;
Tyler Gunn584ba6c2015-12-08 10:53:41 -08001439 private VideoCallImpl mVideoCallImpl;
Hall Liu95d55872017-01-25 17:12:49 -08001440 private RttCall mRttCall;
Ihab Awade63fadb2014-07-09 21:52:04 -07001441 private Details mDetails;
Tyler Gunndee56a82016-03-23 16:06:34 -07001442 private Bundle mExtras;
Ihab Awade63fadb2014-07-09 21:52:04 -07001443
1444 /**
1445 * Obtains the post-dial sequence remaining to be emitted by this {@code Call}, if any.
1446 *
1447 * @return The remaining post-dial sequence, or {@code null} if there is no post-dial sequence
1448 * remaining or this {@code Call} is not in a post-dial state.
1449 */
1450 public String getRemainingPostDialSequence() {
1451 return mRemainingPostDialSequence;
1452 }
1453
1454 /**
1455 * Instructs this {@link #STATE_RINGING} {@code Call} to answer.
Andrew Lee8da4c3c2014-07-16 10:11:42 -07001456 * @param videoState The video state in which to answer the call.
Ihab Awade63fadb2014-07-09 21:52:04 -07001457 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001458 public void answer(@VideoProfile.VideoState int videoState) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001459 mInCallAdapter.answerCall(mTelecomCallId, videoState);
Ihab Awade63fadb2014-07-09 21:52:04 -07001460 }
1461
1462 /**
Pooja Jaind34698d2017-12-28 14:15:31 +05301463 * Instructs this {@link #STATE_RINGING} {@code Call} to deflect.
1464 *
1465 * @param address The address to which the call will be deflected.
1466 */
1467 public void deflect(Uri address) {
1468 mInCallAdapter.deflectCall(mTelecomCallId, address);
1469 }
1470
1471 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001472 * Instructs this {@link #STATE_RINGING} {@code Call} to reject.
1473 *
1474 * @param rejectWithMessage Whether to reject with a text message.
1475 * @param textMessage An optional text message with which to respond.
1476 */
1477 public void reject(boolean rejectWithMessage, String textMessage) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001478 mInCallAdapter.rejectCall(mTelecomCallId, rejectWithMessage, textMessage);
Ihab Awade63fadb2014-07-09 21:52:04 -07001479 }
1480
1481 /**
1482 * Instructs this {@code Call} to disconnect.
1483 */
1484 public void disconnect() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001485 mInCallAdapter.disconnectCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001486 }
1487
1488 /**
1489 * Instructs this {@code Call} to go on hold.
1490 */
1491 public void hold() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001492 mInCallAdapter.holdCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001493 }
1494
1495 /**
1496 * Instructs this {@link #STATE_HOLDING} call to release from hold.
1497 */
1498 public void unhold() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001499 mInCallAdapter.unholdCall(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001500 }
1501
1502 /**
Hall Liu6dfa2492019-10-01 17:20:39 -07001503 * Instructs Telecom to put the call into the background audio processing state.
1504 *
1505 * This method can be called either when the call is in {@link #STATE_RINGING} or
1506 * {@link #STATE_ACTIVE}. After Telecom acknowledges the request by setting the call's state to
1507 * {@link #STATE_AUDIO_PROCESSING}, your app may setup the audio paths with the audio stack in
1508 * order to capture and play audio on the call stream.
1509 *
1510 * This method can only be called by the default dialer app.
1511 * @hide
1512 */
1513 @SystemApi
1514 @TestApi
1515 //@RequiresPermission(android.Manifest.permission.BACKGROUND_CALL_AUDIO)
1516 public void enterBackgroundAudioProcessing() {
1517 if (mState != STATE_ACTIVE && mState != STATE_RINGING) {
1518 throw new IllegalStateException("Call must be active or ringing");
1519 }
1520 mInCallAdapter.enterBackgroundAudioProcessing(mTelecomCallId);
1521 }
1522
1523 /**
1524 * Instructs Telecom to come out of the background audio processing state requested by
1525 * {@link #enterBackgroundAudioProcessing()} or from the call screening service.
1526 *
1527 * This method can only be called when the call is in {@link #STATE_AUDIO_PROCESSING}.
1528 *
1529 * @param shouldRing If true, Telecom will put the call into the
1530 * {@link #STATE_SIMULATED_RINGING} state and notify other apps that there is
1531 * a ringing call. Otherwise, the call will go into {@link #STATE_ACTIVE}
1532 * immediately.
1533 * @hide
1534 */
1535 @SystemApi
1536 @TestApi
1537 //@RequiresPermission(android.Manifest.permission.BACKGROUND_CALL_AUDIO)
1538 public void exitBackgroundAudioProcessing(boolean shouldRing) {
1539 if (mState != STATE_AUDIO_PROCESSING) {
1540 throw new IllegalStateException("Call must in the audio processing state");
1541 }
1542 mInCallAdapter.exitBackgroundAudioProcessing(mTelecomCallId, shouldRing);
1543 }
1544
1545 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001546 * Instructs this {@code Call} to play a dual-tone multi-frequency signaling (DTMF) tone.
1547 *
1548 * Any other currently playing DTMF tone in the specified call is immediately stopped.
1549 *
1550 * @param digit A character representing the DTMF digit for which to play the tone. This
1551 * value must be one of {@code '0'} through {@code '9'}, {@code '*'} or {@code '#'}.
1552 */
1553 public void playDtmfTone(char digit) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001554 mInCallAdapter.playDtmfTone(mTelecomCallId, digit);
Ihab Awade63fadb2014-07-09 21:52:04 -07001555 }
1556
1557 /**
1558 * Instructs this {@code Call} to stop any dual-tone multi-frequency signaling (DTMF) tone
1559 * currently playing.
1560 *
1561 * DTMF tones are played by calling {@link #playDtmfTone(char)}. If no DTMF tone is
1562 * currently playing, this method will do nothing.
1563 */
1564 public void stopDtmfTone() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001565 mInCallAdapter.stopDtmfTone(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001566 }
1567
1568 /**
1569 * Instructs this {@code Call} to continue playing a post-dial DTMF string.
1570 *
1571 * A post-dial DTMF string is a string of digits entered after a phone number, when dialed,
1572 * that are immediately sent as DTMF tones to the recipient as soon as the connection is made.
Ihab Awade63fadb2014-07-09 21:52:04 -07001573 *
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001574 * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_PAUSE} symbol, this
Ihab Awade63fadb2014-07-09 21:52:04 -07001575 * {@code Call} will temporarily pause playing the tones for a pre-defined period of time.
1576 *
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001577 * If the DTMF string contains a {@link TelecomManager#DTMF_CHARACTER_WAIT} symbol, this
Andrew Leeda80c872015-04-15 14:09:50 -07001578 * {@code Call} will pause playing the tones and notify callbacks via
1579 * {@link Callback#onPostDialWait(Call, String)}. At this point, the in-call app
Ihab Awade63fadb2014-07-09 21:52:04 -07001580 * should display to the user an indication of this state and an affordance to continue
1581 * the postdial sequence. When the user decides to continue the postdial sequence, the in-call
1582 * app should invoke the {@link #postDialContinue(boolean)} method.
1583 *
1584 * @param proceed Whether or not to continue with the post-dial sequence.
1585 */
1586 public void postDialContinue(boolean proceed) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001587 mInCallAdapter.postDialContinue(mTelecomCallId, proceed);
Ihab Awade63fadb2014-07-09 21:52:04 -07001588 }
1589
1590 /**
Evan Charlton8c8a0622014-07-20 12:31:00 -07001591 * Notifies this {@code Call} that an account has been selected and to proceed with placing
Nancy Chen36c62f32014-10-21 18:36:39 -07001592 * an outgoing call. Optionally sets this account as the default account.
Nancy Chen5da0fd52014-07-08 14:16:17 -07001593 */
Nancy Chen36c62f32014-10-21 18:36:39 -07001594 public void phoneAccountSelected(PhoneAccountHandle accountHandle, boolean setDefault) {
1595 mInCallAdapter.phoneAccountSelected(mTelecomCallId, accountHandle, setDefault);
Nancy Chen5da0fd52014-07-08 14:16:17 -07001596
1597 }
1598
1599 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001600 * Instructs this {@code Call} to enter a conference.
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001601 *
1602 * @param callToConferenceWith The other call with which to conference.
Ihab Awade63fadb2014-07-09 21:52:04 -07001603 */
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001604 public void conference(Call callToConferenceWith) {
1605 if (callToConferenceWith != null) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001606 mInCallAdapter.conference(mTelecomCallId, callToConferenceWith.mTelecomCallId);
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001607 }
Ihab Awade63fadb2014-07-09 21:52:04 -07001608 }
1609
1610 /**
1611 * Instructs this {@code Call} to split from any conference call with which it may be
1612 * connected.
1613 */
1614 public void splitFromConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001615 mInCallAdapter.splitFromConference(mTelecomCallId);
Ihab Awade63fadb2014-07-09 21:52:04 -07001616 }
1617
1618 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001619 * Merges the calls within this conference. See {@link Details#CAPABILITY_MERGE_CONFERENCE}.
Santos Cordona4868042014-09-04 17:39:22 -07001620 */
1621 public void mergeConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001622 mInCallAdapter.mergeConference(mTelecomCallId);
Santos Cordona4868042014-09-04 17:39:22 -07001623 }
1624
1625 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001626 * Swaps the calls within this conference. See {@link Details#CAPABILITY_SWAP_CONFERENCE}.
Santos Cordona4868042014-09-04 17:39:22 -07001627 */
1628 public void swapConference() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001629 mInCallAdapter.swapConference(mTelecomCallId);
Santos Cordona4868042014-09-04 17:39:22 -07001630 }
1631
1632 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001633 * Initiates a request to the {@link ConnectionService} to pull an external call to the local
1634 * device.
1635 * <p>
1636 * Calls to this method are ignored if the call does not have the
1637 * {@link Call.Details#PROPERTY_IS_EXTERNAL_CALL} property set.
1638 * <p>
1639 * An {@link InCallService} will only see calls which support this method if it has the
1640 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true}
1641 * in its manifest.
1642 */
1643 public void pullExternalCall() {
1644 // If this isn't an external call, ignore the request.
1645 if (!mDetails.hasProperty(Details.PROPERTY_IS_EXTERNAL_CALL)) {
1646 return;
1647 }
1648
1649 mInCallAdapter.pullExternalCall(mTelecomCallId);
1650 }
1651
1652 /**
1653 * Sends a {@code Call} event from this {@code Call} to the associated {@link Connection} in
1654 * the {@link ConnectionService}.
1655 * <p>
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001656 * Call events are used to communicate point in time information from an {@link InCallService}
1657 * to a {@link ConnectionService}. A {@link ConnectionService} implementation could define
1658 * events which enable the {@link InCallService}, for example, toggle a unique feature of the
1659 * {@link ConnectionService}.
1660 * <p>
1661 * A {@link ConnectionService} can communicate to the {@link InCallService} using
1662 * {@link Connection#sendConnectionEvent(String, Bundle)}.
1663 * <p>
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001664 * Events are exposed to {@link ConnectionService} implementations via
1665 * {@link android.telecom.Connection#onCallEvent(String, Bundle)}.
1666 * <p>
1667 * No assumptions should be made as to how a {@link ConnectionService} will handle these events.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001668 * The {@link InCallService} must assume that the {@link ConnectionService} could chose to
1669 * ignore some events altogether.
1670 * <p>
1671 * Events should be fully qualified (e.g., {@code com.example.event.MY_EVENT}) to avoid
1672 * conflicts between {@link InCallService} implementations. Further, {@link InCallService}
1673 * implementations shall not re-purpose events in the {@code android.*} namespace, nor shall
1674 * they define their own event types in this namespace. When defining a custom event type,
1675 * ensure the contents of the extras {@link Bundle} is clearly defined. Extra keys for this
1676 * bundle should be named similar to the event type (e.g. {@code com.example.extra.MY_EXTRA}).
1677 * <p>
1678 * When defining events and the associated extras, it is important to keep their behavior
1679 * consistent when the associated {@link InCallService} is updated. Support for deprecated
1680 * events/extras should me maintained to ensure backwards compatibility with older
1681 * {@link ConnectionService} implementations which were built to support the older behavior.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001682 *
1683 * @param event The connection event.
1684 * @param extras Bundle containing extra information associated with the event.
1685 */
1686 public void sendCallEvent(String event, Bundle extras) {
Sanket Padawef6a9e5b2018-01-05 14:26:16 -08001687 mInCallAdapter.sendCallEvent(mTelecomCallId, event, mTargetSdkVersion, extras);
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001688 }
1689
1690 /**
Hall Liu95d55872017-01-25 17:12:49 -08001691 * Sends an RTT upgrade request to the remote end of the connection. Success is not
1692 * guaranteed, and notification of success will be via the
1693 * {@link Callback#onRttStatusChanged(Call, boolean, RttCall)} callback.
1694 */
1695 public void sendRttRequest() {
Hall Liu57006aa2017-02-06 10:49:48 -08001696 mInCallAdapter.sendRttRequest(mTelecomCallId);
Hall Liu95d55872017-01-25 17:12:49 -08001697 }
1698
1699 /**
1700 * Responds to an RTT request received via the {@link Callback#onRttRequest(Call, int)} )}
1701 * callback.
1702 * The ID used here should be the same as the ID that was received via the callback.
1703 * @param id The request ID received via {@link Callback#onRttRequest(Call, int)}
1704 * @param accept {@code true} if the RTT request should be accepted, {@code false} otherwise.
1705 */
1706 public void respondToRttRequest(int id, boolean accept) {
Hall Liu57006aa2017-02-06 10:49:48 -08001707 mInCallAdapter.respondToRttRequest(mTelecomCallId, id, accept);
Hall Liu95d55872017-01-25 17:12:49 -08001708 }
1709
1710 /**
Sanket Padawea8eddd42017-11-03 11:07:35 -07001711 * Initiates a handover of this {@link Call} to the {@link ConnectionService} identified
1712 * by {@code toHandle}. The videoState specified indicates the desired video state after the
1713 * handover.
1714 * <p>
Tyler Gunn9d127732018-03-02 15:45:51 -08001715 * A call handover is the process where an ongoing call is transferred from one app (i.e.
1716 * {@link ConnectionService} to another app. The user could, for example, choose to continue a
1717 * mobile network call in a video calling app. The mobile network call via the Telephony stack
1718 * is referred to as the source of the handover, and the video calling app is referred to as the
1719 * destination.
1720 * <p>
1721 * When considering a handover scenario the device this method is called on is considered the
1722 * <em>initiating</em> device (since the user initiates the handover from this device), and the
1723 * other device is considered the <em>receiving</em> device.
1724 * <p>
1725 * When this method is called on the <em>initiating</em> device, the Telecom framework will bind
1726 * to the {@link ConnectionService} defined by the {@code toHandle} {@link PhoneAccountHandle}
1727 * and invoke
1728 * {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
1729 * ConnectionRequest)} to inform the destination app that a request has been made to handover a
1730 * call to it. The app returns an instance of {@link Connection} to represent the handover call
1731 * At this point the app should display UI to indicate to the user that a call
1732 * handover is in process.
1733 * <p>
1734 * The destination app is responsible for communicating the handover request from the
1735 * <em>initiating</em> device to the <em>receiving</em> device.
1736 * <p>
1737 * When the app on the <em>receiving</em> device receives the handover request, it calls
1738 * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to continue the handover
1739 * process from the <em>initiating</em> device to the <em>receiving</em> device. At this point
1740 * the destination app on the <em>receiving</em> device should show UI to allow the user to
1741 * choose whether they want to continue their call in the destination app.
1742 * <p>
1743 * When the destination app on the <em>receiving</em> device calls
1744 * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}, Telecom will bind to its
1745 * {@link ConnectionService} and call
1746 * {@link ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle,
1747 * ConnectionRequest)} to inform it of the handover request. The app returns an instance of
1748 * {@link Connection} to represent the handover call.
1749 * <p>
1750 * If the user of the <em>receiving</em> device accepts the handover, the app calls
1751 * {@link Connection#setActive()} to complete the handover process; Telecom will disconnect the
1752 * original call. If the user rejects the handover, the app calls
1753 * {@link Connection#setDisconnected(DisconnectCause)} and specifies a {@link DisconnectCause}
1754 * of {@link DisconnectCause#CANCELED} to indicate that the handover has been cancelled.
1755 * <p>
1756 * Telecom will only allow handovers from {@link PhoneAccount}s which declare
1757 * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}. Similarly, the {@link PhoneAccount}
1758 * specified by {@code toHandle} must declare {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}.
1759 * <p>
1760 * Errors in the handover process are reported to the {@link InCallService} via
1761 * {@link Callback#onHandoverFailed(Call, int)}. Errors in the handover process are reported to
1762 * the involved {@link ConnectionService}s via
1763 * {@link ConnectionService#onHandoverFailed(ConnectionRequest, int)}.
Sanket Padawea8eddd42017-11-03 11:07:35 -07001764 *
1765 * @param toHandle {@link PhoneAccountHandle} of the {@link ConnectionService} to handover
1766 * this call to.
Tyler Gunn9d127732018-03-02 15:45:51 -08001767 * @param videoState Indicates the video state desired after the handover (see the
1768 * {@code STATE_*} constants defined in {@link VideoProfile}).
Sanket Padawea8eddd42017-11-03 11:07:35 -07001769 * @param extras Bundle containing extra information to be passed to the
1770 * {@link ConnectionService}
1771 */
Tyler Gunn9d127732018-03-02 15:45:51 -08001772 public void handoverTo(PhoneAccountHandle toHandle, @VideoProfile.VideoState int videoState,
1773 Bundle extras) {
Sanket Padawea8eddd42017-11-03 11:07:35 -07001774 mInCallAdapter.handoverTo(mTelecomCallId, toHandle, videoState, extras);
1775 }
1776
1777 /**
Hall Liu95d55872017-01-25 17:12:49 -08001778 * Terminate the RTT session on this call. The resulting state change will be notified via
1779 * the {@link Callback#onRttStatusChanged(Call, boolean, RttCall)} callback.
1780 */
1781 public void stopRtt() {
Hall Liu57006aa2017-02-06 10:49:48 -08001782 mInCallAdapter.stopRtt(mTelecomCallId);
Hall Liu95d55872017-01-25 17:12:49 -08001783 }
1784
1785 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07001786 * Adds some extras to this {@link Call}. Existing keys are replaced and new ones are
1787 * added.
1788 * <p>
1789 * No assumptions should be made as to how an In-Call UI or service will handle these
1790 * extras. Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
1791 *
1792 * @param extras The extras to add.
1793 */
1794 public final void putExtras(Bundle extras) {
1795 if (extras == null) {
1796 return;
1797 }
1798
1799 if (mExtras == null) {
1800 mExtras = new Bundle();
1801 }
1802 mExtras.putAll(extras);
1803 mInCallAdapter.putExtras(mTelecomCallId, extras);
1804 }
1805
1806 /**
1807 * Adds a boolean extra to this {@link Call}.
1808 *
1809 * @param key The extra key.
1810 * @param value The value.
1811 * @hide
1812 */
1813 public final void putExtra(String key, boolean value) {
1814 if (mExtras == null) {
1815 mExtras = new Bundle();
1816 }
1817 mExtras.putBoolean(key, value);
1818 mInCallAdapter.putExtra(mTelecomCallId, key, value);
1819 }
1820
1821 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07001822 * Adds an integer extra to this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07001823 *
1824 * @param key The extra key.
1825 * @param value The value.
1826 * @hide
1827 */
1828 public final void putExtra(String key, int value) {
1829 if (mExtras == null) {
1830 mExtras = new Bundle();
1831 }
1832 mExtras.putInt(key, value);
1833 mInCallAdapter.putExtra(mTelecomCallId, key, value);
1834 }
1835
1836 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07001837 * Adds a string extra to this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07001838 *
1839 * @param key The extra key.
1840 * @param value The value.
1841 * @hide
1842 */
1843 public final void putExtra(String key, String value) {
1844 if (mExtras == null) {
1845 mExtras = new Bundle();
1846 }
1847 mExtras.putString(key, value);
1848 mInCallAdapter.putExtra(mTelecomCallId, key, value);
1849 }
1850
1851 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07001852 * Removes extras from this {@link Call}.
Tyler Gunndee56a82016-03-23 16:06:34 -07001853 *
1854 * @param keys The keys of the extras to remove.
1855 */
1856 public final void removeExtras(List<String> keys) {
1857 if (mExtras != null) {
1858 for (String key : keys) {
1859 mExtras.remove(key);
1860 }
1861 if (mExtras.size() == 0) {
1862 mExtras = null;
1863 }
1864 }
1865 mInCallAdapter.removeExtras(mTelecomCallId, keys);
1866 }
1867
1868 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07001869 * Removes extras from this {@link Call}.
1870 *
1871 * @param keys The keys of the extras to remove.
1872 */
1873 public final void removeExtras(String ... keys) {
1874 removeExtras(Arrays.asList(keys));
1875 }
1876
1877 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001878 * Obtains the parent of this {@code Call} in a conference, if any.
1879 *
1880 * @return The parent {@code Call}, or {@code null} if this {@code Call} is not a
1881 * child of any conference {@code Call}s.
1882 */
1883 public Call getParent() {
Santos Cordon823fd3c2014-08-07 18:35:18 -07001884 if (mParentId != null) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001885 return mPhone.internalGetCallByTelecomId(mParentId);
Santos Cordon823fd3c2014-08-07 18:35:18 -07001886 }
1887 return null;
Ihab Awade63fadb2014-07-09 21:52:04 -07001888 }
1889
1890 /**
1891 * Obtains the children of this conference {@code Call}, if any.
1892 *
1893 * @return The children of this {@code Call} if this {@code Call} is a conference, or an empty
1894 * {@code List} otherwise.
1895 */
1896 public List<Call> getChildren() {
Santos Cordon823fd3c2014-08-07 18:35:18 -07001897 if (!mChildrenCached) {
1898 mChildrenCached = true;
1899 mChildren.clear();
1900
1901 for(String id : mChildrenIds) {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07001902 Call call = mPhone.internalGetCallByTelecomId(id);
Santos Cordon823fd3c2014-08-07 18:35:18 -07001903 if (call == null) {
1904 // At least one child was still not found, so do not save true for "cached"
1905 mChildrenCached = false;
1906 } else {
1907 mChildren.add(call);
1908 }
1909 }
1910 }
1911
Ihab Awade63fadb2014-07-09 21:52:04 -07001912 return mUnmodifiableChildren;
1913 }
1914
1915 /**
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001916 * Returns the list of {@code Call}s with which this {@code Call} is allowed to conference.
1917 *
1918 * @return The list of conferenceable {@code Call}s.
1919 */
1920 public List<Call> getConferenceableCalls() {
1921 return mUnmodifiableConferenceableCalls;
1922 }
1923
1924 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07001925 * Obtains the state of this {@code Call}.
1926 *
1927 * @return A state value, chosen from the {@code STATE_*} constants.
1928 */
1929 public int getState() {
1930 return mState;
1931 }
1932
1933 /**
1934 * Obtains a list of canned, pre-configured message responses to present to the user as
1935 * ways of rejecting this {@code Call} using via a text message.
1936 *
1937 * @see #reject(boolean, String)
1938 *
1939 * @return A list of canned text message responses.
1940 */
1941 public List<String> getCannedTextResponses() {
1942 return mCannedTextResponses;
1943 }
1944
1945 /**
1946 * Obtains an object that can be used to display video from this {@code Call}.
1947 *
Andrew Lee50aca232014-07-22 16:41:54 -07001948 * @return An {@code Call.VideoCall}.
Ihab Awade63fadb2014-07-09 21:52:04 -07001949 */
Andrew Lee50aca232014-07-22 16:41:54 -07001950 public InCallService.VideoCall getVideoCall() {
Tyler Gunn584ba6c2015-12-08 10:53:41 -08001951 return mVideoCallImpl;
Ihab Awade63fadb2014-07-09 21:52:04 -07001952 }
1953
1954 /**
1955 * Obtains an object containing call details.
1956 *
1957 * @return A {@link Details} object. Depending on the state of the {@code Call}, the
1958 * result may be {@code null}.
1959 */
1960 public Details getDetails() {
1961 return mDetails;
1962 }
1963
1964 /**
Hall Liu95d55872017-01-25 17:12:49 -08001965 * Returns this call's RttCall object. The {@link RttCall} instance is used to send and
1966 * receive RTT text data, as well as to change the RTT mode.
1967 * @return A {@link Call.RttCall}. {@code null} if there is no active RTT connection.
1968 */
1969 public @Nullable RttCall getRttCall() {
1970 return mRttCall;
1971 }
1972
1973 /**
1974 * Returns whether this call has an active RTT connection.
1975 * @return true if there is a connection, false otherwise.
1976 */
1977 public boolean isRttActive() {
Hall Liue9041242018-02-09 16:40:03 -08001978 return mRttCall != null && mDetails.hasProperty(Details.PROPERTY_RTT);
Hall Liu95d55872017-01-25 17:12:49 -08001979 }
1980
1981 /**
Andrew Leeda80c872015-04-15 14:09:50 -07001982 * Registers a callback to this {@code Call}.
1983 *
1984 * @param callback A {@code Callback}.
1985 */
1986 public void registerCallback(Callback callback) {
Andrew Lee011728f2015-04-23 15:47:06 -07001987 registerCallback(callback, new Handler());
1988 }
1989
1990 /**
1991 * Registers a callback to this {@code Call}.
1992 *
1993 * @param callback A {@code Callback}.
1994 * @param handler A handler which command and status changes will be delivered to.
1995 */
1996 public void registerCallback(Callback callback, Handler handler) {
1997 unregisterCallback(callback);
Roshan Pius1ca62072015-07-07 17:34:51 -07001998 // Don't allow new callback registration if the call is already being destroyed.
1999 if (callback != null && handler != null && mState != STATE_DISCONNECTED) {
Andrew Lee011728f2015-04-23 15:47:06 -07002000 mCallbackRecords.add(new CallbackRecord<Callback>(callback, handler));
2001 }
Andrew Leeda80c872015-04-15 14:09:50 -07002002 }
2003
2004 /**
2005 * Unregisters a callback from this {@code Call}.
2006 *
2007 * @param callback A {@code Callback}.
2008 */
2009 public void unregisterCallback(Callback callback) {
Roshan Pius1ca62072015-07-07 17:34:51 -07002010 // Don't allow callback deregistration if the call is already being destroyed.
2011 if (callback != null && mState != STATE_DISCONNECTED) {
Andrew Lee011728f2015-04-23 15:47:06 -07002012 for (CallbackRecord<Callback> record : mCallbackRecords) {
2013 if (record.getCallback() == callback) {
2014 mCallbackRecords.remove(record);
2015 break;
2016 }
2017 }
Andrew Leeda80c872015-04-15 14:09:50 -07002018 }
2019 }
2020
Santos Cordon3c20d632016-02-25 16:12:35 -08002021 @Override
2022 public String toString() {
2023 return new StringBuilder().
2024 append("Call [id: ").
2025 append(mTelecomCallId).
2026 append(", state: ").
2027 append(stateToString(mState)).
2028 append(", details: ").
2029 append(mDetails).
2030 append("]").toString();
2031 }
2032
2033 /**
2034 * @param state An integer value of a {@code STATE_*} constant.
2035 * @return A string representation of the value.
2036 */
2037 private static String stateToString(int state) {
2038 switch (state) {
2039 case STATE_NEW:
2040 return "NEW";
2041 case STATE_RINGING:
2042 return "RINGING";
2043 case STATE_DIALING:
2044 return "DIALING";
2045 case STATE_ACTIVE:
2046 return "ACTIVE";
2047 case STATE_HOLDING:
2048 return "HOLDING";
2049 case STATE_DISCONNECTED:
2050 return "DISCONNECTED";
2051 case STATE_CONNECTING:
2052 return "CONNECTING";
2053 case STATE_DISCONNECTING:
2054 return "DISCONNECTING";
2055 case STATE_SELECT_PHONE_ACCOUNT:
2056 return "SELECT_PHONE_ACCOUNT";
Hall Liu4e35b642019-10-14 17:50:45 -07002057 case STATE_SIMULATED_RINGING:
2058 return "SIMULATED_RINGING";
2059 case STATE_AUDIO_PROCESSING:
2060 return "AUDIO_PROCESSING";
Santos Cordon3c20d632016-02-25 16:12:35 -08002061 default:
2062 Log.w(Call.class, "Unknown state %d", state);
2063 return "UNKNOWN";
2064 }
2065 }
2066
Andrew Leeda80c872015-04-15 14:09:50 -07002067 /**
Ihab Awade63fadb2014-07-09 21:52:04 -07002068 * Adds a listener to this {@code Call}.
2069 *
2070 * @param listener A {@code Listener}.
Andrew Leeda80c872015-04-15 14:09:50 -07002071 * @deprecated Use {@link #registerCallback} instead.
2072 * @hide
Ihab Awade63fadb2014-07-09 21:52:04 -07002073 */
Andrew Leeda80c872015-04-15 14:09:50 -07002074 @Deprecated
2075 @SystemApi
Ihab Awade63fadb2014-07-09 21:52:04 -07002076 public void addListener(Listener listener) {
Andrew Leeda80c872015-04-15 14:09:50 -07002077 registerCallback(listener);
Ihab Awade63fadb2014-07-09 21:52:04 -07002078 }
2079
2080 /**
2081 * Removes a listener from this {@code Call}.
2082 *
2083 * @param listener A {@code Listener}.
Andrew Leeda80c872015-04-15 14:09:50 -07002084 * @deprecated Use {@link #unregisterCallback} instead.
2085 * @hide
Ihab Awade63fadb2014-07-09 21:52:04 -07002086 */
Andrew Leeda80c872015-04-15 14:09:50 -07002087 @Deprecated
2088 @SystemApi
Ihab Awade63fadb2014-07-09 21:52:04 -07002089 public void removeListener(Listener listener) {
Andrew Leeda80c872015-04-15 14:09:50 -07002090 unregisterCallback(listener);
Ihab Awade63fadb2014-07-09 21:52:04 -07002091 }
2092
2093 /** {@hide} */
Tyler Gunn159f35c2017-03-02 09:28:37 -08002094 Call(Phone phone, String telecomCallId, InCallAdapter inCallAdapter, String callingPackage,
2095 int targetSdkVersion) {
Ihab Awade63fadb2014-07-09 21:52:04 -07002096 mPhone = phone;
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002097 mTelecomCallId = telecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002098 mInCallAdapter = inCallAdapter;
2099 mState = STATE_NEW;
Tyler Gunnb88b3112016-11-09 10:19:23 -08002100 mCallingPackage = callingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08002101 mTargetSdkVersion = targetSdkVersion;
Ihab Awade63fadb2014-07-09 21:52:04 -07002102 }
2103
2104 /** {@hide} */
Tyler Gunnb88b3112016-11-09 10:19:23 -08002105 Call(Phone phone, String telecomCallId, InCallAdapter inCallAdapter, int state,
Tyler Gunn159f35c2017-03-02 09:28:37 -08002106 String callingPackage, int targetSdkVersion) {
Shriram Ganeshddf570e2015-05-31 09:18:48 -07002107 mPhone = phone;
2108 mTelecomCallId = telecomCallId;
2109 mInCallAdapter = inCallAdapter;
2110 mState = state;
Tyler Gunnb88b3112016-11-09 10:19:23 -08002111 mCallingPackage = callingPackage;
Tyler Gunn159f35c2017-03-02 09:28:37 -08002112 mTargetSdkVersion = targetSdkVersion;
Shriram Ganeshddf570e2015-05-31 09:18:48 -07002113 }
2114
2115 /** {@hide} */
Ihab Awade63fadb2014-07-09 21:52:04 -07002116 final String internalGetCallId() {
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002117 return mTelecomCallId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002118 }
2119
2120 /** {@hide} */
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002121 final void internalUpdate(ParcelableCall parcelableCall, Map<String, Call> callIdMap) {
Tyler Gunnb88b3112016-11-09 10:19:23 -08002122
Ihab Awade63fadb2014-07-09 21:52:04 -07002123 // First, we update the internal state as far as possible before firing any updates.
Sailesh Nepal1bef3392016-01-24 18:21:53 -08002124 Details details = Details.createFromParcelableCall(parcelableCall);
Ihab Awade63fadb2014-07-09 21:52:04 -07002125 boolean detailsChanged = !Objects.equals(mDetails, details);
2126 if (detailsChanged) {
2127 mDetails = details;
2128 }
2129
2130 boolean cannedTextResponsesChanged = false;
Santos Cordon88b771d2014-07-19 13:10:40 -07002131 if (mCannedTextResponses == null && parcelableCall.getCannedSmsResponses() != null
2132 && !parcelableCall.getCannedSmsResponses().isEmpty()) {
2133 mCannedTextResponses =
2134 Collections.unmodifiableList(parcelableCall.getCannedSmsResponses());
Yorke Leee886f632015-08-04 13:43:31 -07002135 cannedTextResponsesChanged = true;
Ihab Awade63fadb2014-07-09 21:52:04 -07002136 }
2137
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002138 IVideoProvider previousVideoProvider = mVideoCallImpl == null ? null :
2139 mVideoCallImpl.getVideoProvider();
2140 IVideoProvider newVideoProvider = parcelableCall.getVideoProvider();
2141
2142 // parcelableCall.isVideoCallProviderChanged is only true when we have a video provider
2143 // specified; so we should check if the actual IVideoProvider changes as well.
2144 boolean videoCallChanged = parcelableCall.isVideoCallProviderChanged()
2145 && !Objects.equals(previousVideoProvider, newVideoProvider);
Andrew Lee50aca232014-07-22 16:41:54 -07002146 if (videoCallChanged) {
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002147 if (mVideoCallImpl != null) {
2148 mVideoCallImpl.destroy();
2149 }
2150 mVideoCallImpl = parcelableCall.isVideoCallProviderChanged() ?
2151 parcelableCall.getVideoCallImpl(mCallingPackage, mTargetSdkVersion) : null;
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002152 }
Tyler Gunnd1fdf3a2019-11-05 15:47:58 -08002153
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002154 if (mVideoCallImpl != null) {
2155 mVideoCallImpl.setVideoState(getDetails().getVideoState());
Ihab Awade63fadb2014-07-09 21:52:04 -07002156 }
2157
Santos Cordone3c507b2015-04-23 14:44:19 -07002158 int state = parcelableCall.getState();
Hall Liu31de23d2019-10-11 15:38:29 -07002159 if (mTargetSdkVersion < Phone.SDK_VERSION_R && state == Call.STATE_SIMULATED_RINGING) {
2160 state = Call.STATE_RINGING;
2161 }
Ihab Awade63fadb2014-07-09 21:52:04 -07002162 boolean stateChanged = mState != state;
2163 if (stateChanged) {
2164 mState = state;
2165 }
2166
Santos Cordon823fd3c2014-08-07 18:35:18 -07002167 String parentId = parcelableCall.getParentCallId();
2168 boolean parentChanged = !Objects.equals(mParentId, parentId);
2169 if (parentChanged) {
2170 mParentId = parentId;
Ihab Awade63fadb2014-07-09 21:52:04 -07002171 }
2172
Santos Cordon823fd3c2014-08-07 18:35:18 -07002173 List<String> childCallIds = parcelableCall.getChildCallIds();
2174 boolean childrenChanged = !Objects.equals(childCallIds, mChildrenIds);
2175 if (childrenChanged) {
2176 mChildrenIds.clear();
2177 mChildrenIds.addAll(parcelableCall.getChildCallIds());
2178 mChildrenCached = false;
Ihab Awade63fadb2014-07-09 21:52:04 -07002179 }
2180
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002181 List<String> conferenceableCallIds = parcelableCall.getConferenceableCallIds();
2182 List<Call> conferenceableCalls = new ArrayList<Call>(conferenceableCallIds.size());
2183 for (String otherId : conferenceableCallIds) {
2184 if (callIdMap.containsKey(otherId)) {
2185 conferenceableCalls.add(callIdMap.get(otherId));
2186 }
2187 }
2188
2189 if (!Objects.equals(mConferenceableCalls, conferenceableCalls)) {
2190 mConferenceableCalls.clear();
2191 mConferenceableCalls.addAll(conferenceableCalls);
2192 fireConferenceableCallsChanged();
2193 }
2194
Hall Liu95d55872017-01-25 17:12:49 -08002195 boolean isRttChanged = false;
2196 boolean rttModeChanged = false;
Hall Liue9041242018-02-09 16:40:03 -08002197 if (parcelableCall.getIsRttCallChanged()
2198 && mDetails.hasProperty(Details.PROPERTY_RTT)) {
Hall Liu95d55872017-01-25 17:12:49 -08002199 ParcelableRttCall parcelableRttCall = parcelableCall.getParcelableRttCall();
2200 InputStreamReader receiveStream = new InputStreamReader(
2201 new ParcelFileDescriptor.AutoCloseInputStream(
2202 parcelableRttCall.getReceiveStream()),
2203 StandardCharsets.UTF_8);
2204 OutputStreamWriter transmitStream = new OutputStreamWriter(
2205 new ParcelFileDescriptor.AutoCloseOutputStream(
2206 parcelableRttCall.getTransmitStream()),
2207 StandardCharsets.UTF_8);
Hall Liu57006aa2017-02-06 10:49:48 -08002208 RttCall newRttCall = new Call.RttCall(mTelecomCallId,
Hall Liu95d55872017-01-25 17:12:49 -08002209 receiveStream, transmitStream, parcelableRttCall.getRttMode(), mInCallAdapter);
2210 if (mRttCall == null) {
2211 isRttChanged = true;
2212 } else if (mRttCall.getRttAudioMode() != newRttCall.getRttAudioMode()) {
2213 rttModeChanged = true;
2214 }
2215 mRttCall = newRttCall;
2216 } else if (mRttCall != null && parcelableCall.getParcelableRttCall() == null
2217 && parcelableCall.getIsRttCallChanged()) {
2218 isRttChanged = true;
2219 mRttCall = null;
2220 }
2221
Ihab Awade63fadb2014-07-09 21:52:04 -07002222 // Now we fire updates, ensuring that any client who listens to any of these notifications
2223 // gets the most up-to-date state.
2224
2225 if (stateChanged) {
2226 fireStateChanged(mState);
2227 }
2228 if (detailsChanged) {
2229 fireDetailsChanged(mDetails);
2230 }
2231 if (cannedTextResponsesChanged) {
2232 fireCannedTextResponsesLoaded(mCannedTextResponses);
2233 }
Andrew Lee50aca232014-07-22 16:41:54 -07002234 if (videoCallChanged) {
Tyler Gunn584ba6c2015-12-08 10:53:41 -08002235 fireVideoCallChanged(mVideoCallImpl);
Ihab Awade63fadb2014-07-09 21:52:04 -07002236 }
Santos Cordon823fd3c2014-08-07 18:35:18 -07002237 if (parentChanged) {
2238 fireParentChanged(getParent());
2239 }
2240 if (childrenChanged) {
2241 fireChildrenChanged(getChildren());
2242 }
Hall Liu95d55872017-01-25 17:12:49 -08002243 if (isRttChanged) {
2244 fireOnIsRttChanged(mRttCall != null, mRttCall);
2245 }
2246 if (rttModeChanged) {
2247 fireOnRttModeChanged(mRttCall.getRttAudioMode());
2248 }
Ihab Awade63fadb2014-07-09 21:52:04 -07002249
2250 // If we have transitioned to DISCONNECTED, that means we need to notify clients and
2251 // remove ourselves from the Phone. Note that we do this after completing all state updates
2252 // so a client can cleanly transition all their UI to the state appropriate for a
2253 // DISCONNECTED Call while still relying on the existence of that Call in the Phone's list.
2254 if (mState == STATE_DISCONNECTED) {
2255 fireCallDestroyed();
Ihab Awade63fadb2014-07-09 21:52:04 -07002256 }
2257 }
2258
2259 /** {@hide} */
Ihab Awade63fadb2014-07-09 21:52:04 -07002260 final void internalSetPostDialWait(String remaining) {
2261 mRemainingPostDialSequence = remaining;
2262 firePostDialWait(mRemainingPostDialSequence);
2263 }
2264
Sailesh Nepal2ab88cc2014-07-18 14:49:18 -07002265 /** {@hide} */
Santos Cordonf30d7e92014-08-26 09:54:33 -07002266 final void internalSetDisconnected() {
2267 if (mState != Call.STATE_DISCONNECTED) {
2268 mState = Call.STATE_DISCONNECTED;
2269 fireStateChanged(mState);
2270 fireCallDestroyed();
Santos Cordonf30d7e92014-08-26 09:54:33 -07002271 }
2272 }
2273
Tyler Gunn876dbfb2016-03-14 15:18:07 -07002274 /** {@hide} */
2275 final void internalOnConnectionEvent(String event, Bundle extras) {
2276 fireOnConnectionEvent(event, extras);
2277 }
2278
Hall Liu95d55872017-01-25 17:12:49 -08002279 /** {@hide} */
2280 final void internalOnRttUpgradeRequest(final int requestId) {
2281 for (CallbackRecord<Callback> record : mCallbackRecords) {
2282 final Call call = this;
2283 final Callback callback = record.getCallback();
2284 record.getHandler().post(() -> callback.onRttRequest(call, requestId));
2285 }
2286 }
2287
Hall Liu57006aa2017-02-06 10:49:48 -08002288 /** @hide */
2289 final void internalOnRttInitiationFailure(int reason) {
2290 for (CallbackRecord<Callback> record : mCallbackRecords) {
2291 final Call call = this;
2292 final Callback callback = record.getCallback();
2293 record.getHandler().post(() -> callback.onRttInitiationFailure(call, reason));
2294 }
2295 }
2296
Sanket Padawe85291f62017-12-01 13:59:27 -08002297 /** {@hide} */
2298 final void internalOnHandoverFailed(int error) {
2299 for (CallbackRecord<Callback> record : mCallbackRecords) {
2300 final Call call = this;
2301 final Callback callback = record.getCallback();
2302 record.getHandler().post(() -> callback.onHandoverFailed(call, error));
2303 }
2304 }
2305
Tyler Gunn858bfaf2018-01-22 15:17:54 -08002306 /** {@hide} */
2307 final void internalOnHandoverComplete() {
2308 for (CallbackRecord<Callback> record : mCallbackRecords) {
2309 final Call call = this;
2310 final Callback callback = record.getCallback();
2311 record.getHandler().post(() -> callback.onHandoverComplete(call));
2312 }
2313 }
2314
Andrew Lee011728f2015-04-23 15:47:06 -07002315 private void fireStateChanged(final int newState) {
2316 for (CallbackRecord<Callback> record : mCallbackRecords) {
2317 final Call call = this;
2318 final Callback callback = record.getCallback();
2319 record.getHandler().post(new Runnable() {
2320 @Override
2321 public void run() {
2322 callback.onStateChanged(call, newState);
2323 }
2324 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002325 }
2326 }
2327
Andrew Lee011728f2015-04-23 15:47:06 -07002328 private void fireParentChanged(final Call newParent) {
2329 for (CallbackRecord<Callback> record : mCallbackRecords) {
2330 final Call call = this;
2331 final Callback callback = record.getCallback();
2332 record.getHandler().post(new Runnable() {
2333 @Override
2334 public void run() {
2335 callback.onParentChanged(call, newParent);
2336 }
2337 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002338 }
2339 }
2340
Andrew Lee011728f2015-04-23 15:47:06 -07002341 private void fireChildrenChanged(final List<Call> children) {
2342 for (CallbackRecord<Callback> record : mCallbackRecords) {
2343 final Call call = this;
2344 final Callback callback = record.getCallback();
2345 record.getHandler().post(new Runnable() {
2346 @Override
2347 public void run() {
2348 callback.onChildrenChanged(call, children);
2349 }
2350 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002351 }
2352 }
2353
Andrew Lee011728f2015-04-23 15:47:06 -07002354 private void fireDetailsChanged(final Details details) {
2355 for (CallbackRecord<Callback> record : mCallbackRecords) {
2356 final Call call = this;
2357 final Callback callback = record.getCallback();
2358 record.getHandler().post(new Runnable() {
2359 @Override
2360 public void run() {
2361 callback.onDetailsChanged(call, details);
2362 }
2363 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002364 }
2365 }
2366
Andrew Lee011728f2015-04-23 15:47:06 -07002367 private void fireCannedTextResponsesLoaded(final List<String> cannedTextResponses) {
2368 for (CallbackRecord<Callback> record : mCallbackRecords) {
2369 final Call call = this;
2370 final Callback callback = record.getCallback();
2371 record.getHandler().post(new Runnable() {
2372 @Override
2373 public void run() {
2374 callback.onCannedTextResponsesLoaded(call, cannedTextResponses);
2375 }
2376 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002377 }
2378 }
2379
Andrew Lee011728f2015-04-23 15:47:06 -07002380 private void fireVideoCallChanged(final InCallService.VideoCall videoCall) {
2381 for (CallbackRecord<Callback> record : mCallbackRecords) {
2382 final Call call = this;
2383 final Callback callback = record.getCallback();
2384 record.getHandler().post(new Runnable() {
2385 @Override
2386 public void run() {
2387 callback.onVideoCallChanged(call, videoCall);
2388 }
2389 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002390 }
2391 }
2392
Andrew Lee011728f2015-04-23 15:47:06 -07002393 private void firePostDialWait(final String remainingPostDialSequence) {
2394 for (CallbackRecord<Callback> record : mCallbackRecords) {
2395 final Call call = this;
2396 final Callback callback = record.getCallback();
2397 record.getHandler().post(new Runnable() {
2398 @Override
2399 public void run() {
2400 callback.onPostDialWait(call, remainingPostDialSequence);
2401 }
2402 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002403 }
2404 }
2405
2406 private void fireCallDestroyed() {
Roshan Pius1ca62072015-07-07 17:34:51 -07002407 /**
2408 * To preserve the ordering of the Call's onCallDestroyed callback and Phone's
2409 * onCallRemoved callback, we remove this call from the Phone's record
2410 * only once all of the registered onCallDestroyed callbacks are executed.
2411 * All the callbacks get removed from our records as a part of this operation
2412 * since onCallDestroyed is the final callback.
2413 */
2414 final Call call = this;
2415 if (mCallbackRecords.isEmpty()) {
2416 // No callbacks registered, remove the call from Phone's record.
2417 mPhone.internalRemoveCall(call);
2418 }
2419 for (final CallbackRecord<Callback> record : mCallbackRecords) {
Andrew Lee011728f2015-04-23 15:47:06 -07002420 final Callback callback = record.getCallback();
2421 record.getHandler().post(new Runnable() {
2422 @Override
2423 public void run() {
Roshan Pius1ca62072015-07-07 17:34:51 -07002424 boolean isFinalRemoval = false;
2425 RuntimeException toThrow = null;
2426 try {
2427 callback.onCallDestroyed(call);
2428 } catch (RuntimeException e) {
2429 toThrow = e;
2430 }
2431 synchronized(Call.this) {
2432 mCallbackRecords.remove(record);
2433 if (mCallbackRecords.isEmpty()) {
2434 isFinalRemoval = true;
2435 }
2436 }
2437 if (isFinalRemoval) {
2438 mPhone.internalRemoveCall(call);
2439 }
2440 if (toThrow != null) {
2441 throw toThrow;
2442 }
Andrew Lee011728f2015-04-23 15:47:06 -07002443 }
2444 });
Ihab Awade63fadb2014-07-09 21:52:04 -07002445 }
2446 }
2447
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002448 private void fireConferenceableCallsChanged() {
Andrew Lee011728f2015-04-23 15:47:06 -07002449 for (CallbackRecord<Callback> record : mCallbackRecords) {
2450 final Call call = this;
2451 final Callback callback = record.getCallback();
2452 record.getHandler().post(new Runnable() {
2453 @Override
2454 public void run() {
2455 callback.onConferenceableCallsChanged(call, mUnmodifiableConferenceableCalls);
2456 }
2457 });
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002458 }
2459 }
Tyler Gunn1e9bfc62015-08-19 11:18:58 -07002460
2461 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -07002462 * Notifies listeners of an incoming connection event.
2463 * <p>
2464 * Connection events are issued via {@link Connection#sendConnectionEvent(String, Bundle)}.
2465 *
2466 * @param event
2467 * @param extras
2468 */
2469 private void fireOnConnectionEvent(final String event, final Bundle extras) {
2470 for (CallbackRecord<Callback> record : mCallbackRecords) {
2471 final Call call = this;
2472 final Callback callback = record.getCallback();
2473 record.getHandler().post(new Runnable() {
2474 @Override
2475 public void run() {
2476 callback.onConnectionEvent(call, event, extras);
2477 }
2478 });
2479 }
2480 }
2481
2482 /**
Hall Liu95d55872017-01-25 17:12:49 -08002483 * Notifies listeners of an RTT on/off change
2484 *
2485 * @param enabled True if RTT is now enabled, false otherwise
2486 */
2487 private void fireOnIsRttChanged(final boolean enabled, final RttCall rttCall) {
2488 for (CallbackRecord<Callback> record : mCallbackRecords) {
2489 final Call call = this;
2490 final Callback callback = record.getCallback();
2491 record.getHandler().post(() -> callback.onRttStatusChanged(call, enabled, rttCall));
2492 }
2493 }
2494
2495 /**
2496 * Notifies listeners of a RTT mode change
2497 *
2498 * @param mode The new RTT mode
2499 */
2500 private void fireOnRttModeChanged(final int mode) {
2501 for (CallbackRecord<Callback> record : mCallbackRecords) {
2502 final Call call = this;
2503 final Callback callback = record.getCallback();
2504 record.getHandler().post(() -> callback.onRttModeChanged(call, mode));
2505 }
2506 }
2507
2508 /**
Tyler Gunn1e9bfc62015-08-19 11:18:58 -07002509 * Determines if two bundles are equal.
2510 *
2511 * @param bundle The original bundle.
2512 * @param newBundle The bundle to compare with.
2513 * @retrun {@code true} if the bundles are equal, {@code false} otherwise.
2514 */
2515 private static boolean areBundlesEqual(Bundle bundle, Bundle newBundle) {
2516 if (bundle == null || newBundle == null) {
2517 return bundle == newBundle;
2518 }
2519
2520 if (bundle.size() != newBundle.size()) {
2521 return false;
2522 }
2523
2524 for(String key : bundle.keySet()) {
2525 if (key != null) {
2526 final Object value = bundle.get(key);
2527 final Object newValue = newBundle.get(key);
2528 if (!Objects.equals(value, newValue)) {
2529 return false;
2530 }
2531 }
2532 }
2533 return true;
2534 }
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002535}