blob: 089a948b6e55fa285139788445ba1d3f8797d94b [file] [log] [blame]
Ihab Awad542e0ea2014-05-16 10:22:16 -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 Awad542e0ea2014-05-16 10:22:16 -070018
Tyler Gunnc9503d62020-01-27 10:30:51 -080019import static android.Manifest.permission.MODIFY_PHONE_STATE;
20
Hall Liu49cabcc2021-01-15 11:41:48 -080021import android.Manifest;
Tyler Gunnc9503d62020-01-27 10:30:51 -080022import android.annotation.ElapsedRealtimeLong;
Tyler Gunnd57d76c2019-09-24 14:53:23 -070023import android.annotation.IntDef;
Tyler Gunnc9503d62020-01-27 10:30:51 -080024import android.annotation.IntRange;
Tyler Gunndee56a82016-03-23 16:06:34 -070025import android.annotation.NonNull;
Santos Cordon6b7f9552015-05-27 17:21:45 -070026import android.annotation.Nullable;
Tyler Gunnc9503d62020-01-27 10:30:51 -080027import android.annotation.RequiresPermission;
Yorke Lee4af59352015-05-13 14:14:54 -070028import android.annotation.SystemApi;
Tyler Gunn159f35c2017-03-02 09:28:37 -080029import android.app.Notification;
Hall Liua98f58b52017-11-07 17:59:28 -080030import android.bluetooth.BluetoothDevice;
Artur Satayev53ada2a2019-12-10 17:47:56 +000031import android.compat.annotation.UnsupportedAppUsage;
Tyler Gunn159f35c2017-03-02 09:28:37 -080032import android.content.Intent;
Tyler Gunnb702ef82015-05-29 11:51:53 -070033import android.hardware.camera2.CameraManager;
Ihab Awad542e0ea2014-05-16 10:22:16 -070034import android.net.Uri;
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -080035import android.os.Binder;
Santos Cordon6b7f9552015-05-27 17:21:45 -070036import android.os.Bundle;
Ihab Awadb19a0bc2014-08-07 19:46:01 -070037import android.os.Handler;
38import android.os.IBinder;
Tyler Gunn4e9bbaf2015-05-22 15:43:28 -070039import android.os.Looper;
Ihab Awadb19a0bc2014-08-07 19:46:01 -070040import android.os.Message;
Hall Liu95d55872017-01-25 17:12:49 -080041import android.os.ParcelFileDescriptor;
Ihab Awadb19a0bc2014-08-07 19:46:01 -070042import android.os.RemoteException;
Tyler Gunn3fa819c2017-08-04 09:27:26 -070043import android.os.SystemClock;
allenwtsu2aca9892019-11-25 14:38:21 +080044import android.telephony.ims.ImsStreamMediaProfile;
Tyler Gunndee56a82016-03-23 16:06:34 -070045import android.util.ArraySet;
Ihab Awadb19a0bc2014-08-07 19:46:01 -070046import android.view.Surface;
Ihab Awad542e0ea2014-05-16 10:22:16 -070047
Youming Yed6de26e2019-01-30 11:20:35 -080048import com.android.internal.os.SomeArgs;
49import com.android.internal.telecom.IVideoCallback;
50import com.android.internal.telecom.IVideoProvider;
51
Hall Liua549fed2018-02-09 16:40:03 -080052import java.io.FileInputStream;
53import java.io.FileOutputStream;
Hall Liu95d55872017-01-25 17:12:49 -080054import java.io.IOException;
55import java.io.InputStreamReader;
56import java.io.OutputStreamWriter;
Tyler Gunnd57d76c2019-09-24 14:53:23 -070057import java.lang.annotation.Retention;
58import java.lang.annotation.RetentionPolicy;
Hall Liu730a2592018-06-25 19:48:33 -070059import java.nio.channels.Channels;
Santos Cordonb6939982014-06-04 20:20:58 -070060import java.util.ArrayList;
Tyler Gunn071be6f2016-05-10 14:52:33 -070061import java.util.Arrays;
Ihab Awadb19a0bc2014-08-07 19:46:01 -070062import java.util.Collections;
Santos Cordonb6939982014-06-04 20:20:58 -070063import java.util.List;
Ihab Awad542e0ea2014-05-16 10:22:16 -070064import java.util.Set;
Jay Shrauner229e3822014-08-15 09:23:07 -070065import java.util.concurrent.ConcurrentHashMap;
Ihab Awad542e0ea2014-05-16 10:22:16 -070066
67/**
Santos Cordon895d4b82015-06-25 16:41:48 -070068 * Represents a phone call or connection to a remote endpoint that carries voice and/or video
69 * traffic.
Ihab Awad6107bab2014-08-18 09:23:25 -070070 * <p>
71 * Implementations create a custom subclass of {@code Connection} and return it to the framework
72 * as the return value of
73 * {@link ConnectionService#onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)}
74 * or
75 * {@link ConnectionService#onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}.
76 * Implementations are then responsible for updating the state of the {@code Connection}, and
77 * must call {@link #destroy()} to signal to the framework that the {@code Connection} is no
78 * longer used and associated resources may be recovered.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -070079 * <p>
80 * Subclasses of {@code Connection} override the {@code on*} methods to provide the the
81 * {@link ConnectionService}'s implementation of calling functionality. The {@code on*} methods are
82 * called by Telecom to inform an instance of a {@code Connection} of actions specific to that
83 * {@code Connection} instance.
84 * <p>
85 * Basic call support requires overriding the following methods: {@link #onAnswer()},
86 * {@link #onDisconnect()}, {@link #onReject()}, {@link #onAbort()}
87 * <p>
88 * Where a {@code Connection} has {@link #CAPABILITY_SUPPORT_HOLD}, the {@link #onHold()} and
89 * {@link #onUnhold()} methods should be overridden to provide hold support for the
90 * {@code Connection}.
91 * <p>
92 * Where a {@code Connection} supports a variation of video calling (e.g. the
93 * {@code CAPABILITY_SUPPORTS_VT_*} capability bits), {@link #onAnswer(int)} should be overridden
94 * to support answering a call as a video call.
95 * <p>
96 * Where a {@code Connection} has {@link #PROPERTY_IS_EXTERNAL_CALL} and
97 * {@link #CAPABILITY_CAN_PULL_CALL}, {@link #onPullExternalCall()} should be overridden to provide
98 * support for pulling the external call.
99 * <p>
100 * Where a {@code Connection} supports conference calling {@link #onSeparate()} should be
101 * overridden.
102 * <p>
103 * There are a number of other {@code on*} methods which a {@code Connection} can choose to
104 * implement, depending on whether it is concerned with the associated calls from Telecom. If,
105 * for example, call events from a {@link InCallService} are handled,
106 * {@link #onCallEvent(String, Bundle)} should be overridden. Another example is
107 * {@link #onExtrasChanged(Bundle)}, which should be overridden if the {@code Connection} wishes to
108 * make use of extra information provided via the {@link Call#putExtras(Bundle)} and
109 * {@link Call#removeExtras(String...)} methods.
Ihab Awad542e0ea2014-05-16 10:22:16 -0700110 */
Yorke Leeabfcfdc2015-05-13 18:55:18 -0700111public abstract class Connection extends Conferenceable {
Ihab Awad542e0ea2014-05-16 10:22:16 -0700112
Tyler Gunn50d437f2021-01-12 16:34:59 -0800113 /**@hide*/
114 @Retention(RetentionPolicy.SOURCE)
115 @IntDef(prefix = "STATE_", value = {
116 STATE_INITIALIZING,
117 STATE_NEW,
118 STATE_RINGING,
119 STATE_DIALING,
120 STATE_ACTIVE,
121 STATE_HOLDING,
122 STATE_DISCONNECTED,
123 STATE_PULLING_CALL
124 })
125 public @interface ConnectionState {}
126
Santos Cordon895d4b82015-06-25 16:41:48 -0700127 /**
128 * The connection is initializing. This is generally the first state for a {@code Connection}
129 * returned by a {@link ConnectionService}.
130 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700131 public static final int STATE_INITIALIZING = 0;
132
Santos Cordon895d4b82015-06-25 16:41:48 -0700133 /**
134 * The connection is new and not connected.
135 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700136 public static final int STATE_NEW = 1;
137
Santos Cordon895d4b82015-06-25 16:41:48 -0700138 /**
139 * An incoming connection is in the ringing state. During this state, the user's ringer or
140 * vibration feature will be activated.
141 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700142 public static final int STATE_RINGING = 2;
143
Santos Cordon895d4b82015-06-25 16:41:48 -0700144 /**
145 * An outgoing connection is in the dialing state. In this state the other party has not yet
146 * answered the call and the user traditionally hears a ringback tone.
147 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700148 public static final int STATE_DIALING = 3;
149
Santos Cordon895d4b82015-06-25 16:41:48 -0700150 /**
151 * A connection is active. Both parties are connected to the call and can actively communicate.
152 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700153 public static final int STATE_ACTIVE = 4;
154
Santos Cordon895d4b82015-06-25 16:41:48 -0700155 /**
156 * A connection is on hold.
157 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700158 public static final int STATE_HOLDING = 5;
159
Santos Cordon895d4b82015-06-25 16:41:48 -0700160 /**
161 * A connection has been disconnected. This is the final state once the user has been
162 * disconnected from a call either locally, remotely or by an error in the service.
163 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700164 public static final int STATE_DISCONNECTED = 6;
165
Santos Cordon895d4b82015-06-25 16:41:48 -0700166 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700167 * The state of an external connection which is in the process of being pulled from a remote
168 * device to the local device.
169 * <p>
Tyler Gunn720c6642016-03-22 09:02:47 -0700170 * A connection can only be in this state if the {@link #PROPERTY_IS_EXTERNAL_CALL} property and
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700171 * {@link #CAPABILITY_CAN_PULL_CALL} capability bits are set on the connection.
172 */
173 public static final int STATE_PULLING_CALL = 7;
174
175 /**
Tyler Gunnd57d76c2019-09-24 14:53:23 -0700176 * Indicates that the network could not perform verification.
177 */
178 public static final int VERIFICATION_STATUS_NOT_VERIFIED = 0;
179
180 /**
181 * Indicates that verification by the network passed. This indicates there is a high likelihood
182 * that the call originated from a valid source.
183 */
184 public static final int VERIFICATION_STATUS_PASSED = 1;
185
186 /**
187 * Indicates that verification by the network failed. This indicates there is a high likelihood
188 * that the call did not originate from a valid source.
189 */
190 public static final int VERIFICATION_STATUS_FAILED = 2;
191
192 /**@hide*/
193 @Retention(RetentionPolicy.SOURCE)
194 @IntDef(prefix = "VERIFICATION_STATUS_", value = {
195 VERIFICATION_STATUS_NOT_VERIFIED,
196 VERIFICATION_STATUS_PASSED,
197 VERIFICATION_STATUS_FAILED
198 })
199 public @interface VerificationStatus {}
200
201 /**
Santos Cordon895d4b82015-06-25 16:41:48 -0700202 * Connection can currently be put on hold or unheld. This is distinct from
203 * {@link #CAPABILITY_SUPPORT_HOLD} in that although a connection may support 'hold' most times,
204 * it does not at the moment support the function. This can be true while the call is in the
205 * state {@link #STATE_DIALING}, for example. During this condition, an in-call UI may
206 * display a disabled 'hold' button.
207 */
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800208 public static final int CAPABILITY_HOLD = 0x00000001;
209
210 /** Connection supports the hold feature. */
211 public static final int CAPABILITY_SUPPORT_HOLD = 0x00000002;
212
213 /**
214 * Connections within a conference can be merged. A {@link ConnectionService} has the option to
215 * add a {@link Conference} before the child {@link Connection}s are merged. This is how
216 * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this
217 * capability allows a merge button to be shown while the conference is in the foreground
218 * of the in-call UI.
219 * <p>
220 * This is only intended for use by a {@link Conference}.
221 */
222 public static final int CAPABILITY_MERGE_CONFERENCE = 0x00000004;
223
224 /**
225 * Connections within a conference can be swapped between foreground and background.
226 * See {@link #CAPABILITY_MERGE_CONFERENCE} for additional information.
227 * <p>
228 * This is only intended for use by a {@link Conference}.
229 */
230 public static final int CAPABILITY_SWAP_CONFERENCE = 0x00000008;
231
232 /**
233 * @hide
234 */
235 public static final int CAPABILITY_UNUSED = 0x00000010;
236
237 /** Connection supports responding via text option. */
238 public static final int CAPABILITY_RESPOND_VIA_TEXT = 0x00000020;
239
240 /** Connection can be muted. */
241 public static final int CAPABILITY_MUTE = 0x00000040;
242
243 /**
244 * Connection supports conference management. This capability only applies to
245 * {@link Conference}s which can have {@link Connection}s as children.
246 */
247 public static final int CAPABILITY_MANAGE_CONFERENCE = 0x00000080;
248
249 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700250 * Local device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800251 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700252 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_RX = 0x00000100;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800253
254 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700255 * Local device supports transmitting video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800256 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700257 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_TX = 0x00000200;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800258
259 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700260 * Local device supports bidirectional video calling.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800261 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700262 public static final int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700263 CAPABILITY_SUPPORTS_VT_LOCAL_RX | CAPABILITY_SUPPORTS_VT_LOCAL_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800264
265 /**
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700266 * Remote device supports receiving video.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800267 */
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700268 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_RX = 0x00000400;
269
270 /**
271 * Remote device supports transmitting video.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700272 */
273 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_TX = 0x00000800;
274
275 /**
276 * Remote device supports bidirectional video calling.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700277 */
Andrew Lee9a8f9ce2015-04-10 18:09:46 -0700278 public static final int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL =
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700279 CAPABILITY_SUPPORTS_VT_REMOTE_RX | CAPABILITY_SUPPORTS_VT_REMOTE_TX;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800280
281 /**
282 * Connection is able to be separated from its parent {@code Conference}, if any.
283 */
284 public static final int CAPABILITY_SEPARATE_FROM_CONFERENCE = 0x00001000;
285
286 /**
287 * Connection is able to be individually disconnected when in a {@code Conference}.
288 */
289 public static final int CAPABILITY_DISCONNECT_FROM_CONFERENCE = 0x00002000;
290
291 /**
Tyler Gunn720c6642016-03-22 09:02:47 -0700292 * Un-used.
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800293 * @hide
294 */
Tyler Gunn720c6642016-03-22 09:02:47 -0700295 public static final int CAPABILITY_UNUSED_2 = 0x00004000;
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800296
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700297 /**
Tyler Gunn720c6642016-03-22 09:02:47 -0700298 * Un-used.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700299 * @hide
300 */
Tyler Gunn720c6642016-03-22 09:02:47 -0700301 public static final int CAPABILITY_UNUSED_3 = 0x00008000;
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700302
303 /**
Tyler Gunn720c6642016-03-22 09:02:47 -0700304 * Un-used.
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700305 * @hide
306 */
Tyler Gunn720c6642016-03-22 09:02:47 -0700307 public static final int CAPABILITY_UNUSED_4 = 0x00010000;
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700308
Tyler Gunn068085b2015-02-06 13:56:52 -0800309 /**
Tyler Gunn720c6642016-03-22 09:02:47 -0700310 * Un-used.
Tyler Gunn068085b2015-02-06 13:56:52 -0800311 * @hide
312 */
Tyler Gunn720c6642016-03-22 09:02:47 -0700313 public static final int CAPABILITY_UNUSED_5 = 0x00020000;
Tyler Gunn068085b2015-02-06 13:56:52 -0800314
Tyler Gunn96d6c402015-03-18 12:39:23 -0700315 /**
Dong Zhou89f41eb2015-03-15 11:59:49 -0500316 * Speed up audio setup for MT call.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700317 * <p>
318 * Used for IMS calls to indicate that mobile-terminated (incoming) call audio setup should take
319 * place as soon as the device answers the call, but prior to it being connected. This is an
320 * optimization some IMS stacks depend on to ensure prompt setup of call audio.
Dong Zhou89f41eb2015-03-15 11:59:49 -0500321 * @hide
Tyler Gunn96d6c402015-03-18 12:39:23 -0700322 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700323 @SystemApi
Tyler Gunn96d6c402015-03-18 12:39:23 -0700324 public static final int CAPABILITY_SPEED_UP_MT_AUDIO = 0x00040000;
Tyler Gunn068085b2015-02-06 13:56:52 -0800325
Rekha Kumar07366812015-03-24 16:42:31 -0700326 /**
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700327 * Call can be upgraded to a video call.
Tyler Gunn6e3ecc42018-11-12 11:30:56 -0800328 * @deprecated Use {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
329 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL} to indicate for a call whether or not
330 * video calling is supported.
Rekha Kumar07366812015-03-24 16:42:31 -0700331 */
332 public static final int CAPABILITY_CAN_UPGRADE_TO_VIDEO = 0x00080000;
333
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700334 /**
335 * For video calls, indicates whether the outgoing video for the call can be paused using
Yorke Lee32f24732015-05-12 16:18:03 -0700336 * the {@link android.telecom.VideoProfile#STATE_PAUSED} VideoState.
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -0700337 */
338 public static final int CAPABILITY_CAN_PAUSE_VIDEO = 0x00100000;
339
Tyler Gunnd4091732015-06-29 09:15:37 -0700340 /**
341 * For a conference, indicates the conference will not have child connections.
342 * <p>
343 * An example of a conference with child connections is a GSM conference call, where the radio
344 * retains connections to the individual participants of the conference. Another example is an
345 * IMS conference call where conference event package functionality is supported; in this case
346 * the conference server ensures the radio is aware of the participants in the conference, which
347 * are represented by child connections.
348 * <p>
349 * An example of a conference with no child connections is an IMS conference call with no
350 * conference event package support. Such a conference is represented by the radio as a single
351 * connection to the IMS conference server.
352 * <p>
353 * Indicating whether a conference has children or not is important to help user interfaces
354 * visually represent a conference. A conference with no children, for example, will have the
355 * conference connection shown in the list of calls on a Bluetooth device, where if the
356 * conference has children, only the children will be shown in the list of calls on a Bluetooth
357 * device.
358 * @hide
359 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700360 @SystemApi
Tyler Gunnd4091732015-06-29 09:15:37 -0700361 public static final int CAPABILITY_CONFERENCE_HAS_NO_CHILDREN = 0x00200000;
362
Bryce Lee81901682015-08-28 16:38:02 -0700363 /**
364 * Indicates that the connection itself wants to handle any sort of reply response, rather than
365 * relying on SMS.
Bryce Lee81901682015-08-28 16:38:02 -0700366 */
367 public static final int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION = 0x00400000;
368
Tyler Gunnf97a0092016-01-19 15:59:34 -0800369 /**
370 * When set, prevents a video call from being downgraded to an audio-only call.
371 * <p>
372 * Should be set when the VideoState has the {@link VideoProfile#STATE_TX_ENABLED} or
373 * {@link VideoProfile#STATE_RX_ENABLED} bits set to indicate that the connection cannot be
374 * downgraded from a video call back to a VideoState of
375 * {@link VideoProfile#STATE_AUDIO_ONLY}.
376 * <p>
377 * Intuitively, a call which can be downgraded to audio should also have local and remote
378 * video
379 * capabilities (see {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
380 * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL}).
381 */
382 public static final int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO = 0x00800000;
383
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700384 /**
Tyler Gunn720c6642016-03-22 09:02:47 -0700385 * When set for an external connection, indicates that this {@code Connection} can be pulled
386 * from a remote device to the current device.
387 * <p>
388 * Should only be set on a {@code Connection} where {@link #PROPERTY_IS_EXTERNAL_CALL}
389 * is set.
390 */
391 public static final int CAPABILITY_CAN_PULL_CALL = 0x01000000;
392
Pooja Jaind34698d2017-12-28 14:15:31 +0530393 /** Call supports the deflect feature. */
394 public static final int CAPABILITY_SUPPORT_DEFLECT = 0x02000000;
395
Ravi Paluri404babb2020-01-23 19:02:44 +0530396 /**
397 * When set, indicates that this {@link Connection} supports initiation of a conference call
Grace Jia8587ee52020-07-10 15:42:32 -0700398 * by directly adding participants using {@link #onAddConferenceParticipants(List)}. When
399 * participants are added to a {@link Connection}, it will be replaced by a {@link Conference}
400 * instance with {@link #PROPERTY_IS_ADHOC_CONFERENCE} set to indicate that it is an adhoc
401 * conference call.
Ravi Paluri404babb2020-01-23 19:02:44 +0530402 */
403 public static final int CAPABILITY_ADD_PARTICIPANT = 0x04000000;
Ravi Palurif4b38e72020-02-05 12:35:41 +0530404
405 /**
406 * Indicates that this {@code Connection} can be transferred to another
407 * number.
Tyler Gunn460360d2020-07-29 10:21:45 -0700408 * Connection supports the confirmed and unconfirmed call transfer feature.
Ravi Palurif4b38e72020-02-05 12:35:41 +0530409 * @hide
410 */
411 public static final int CAPABILITY_TRANSFER = 0x08000000;
412
413 /**
414 * Indicates that this {@code Connection} can be transferred to another
415 * ongoing {@code Connection}.
416 * Connection supports the consultative call transfer feature.
417 * @hide
418 */
419 public static final int CAPABILITY_TRANSFER_CONSULTATIVE = 0x10000000;
420
Tyler Gunn720c6642016-03-22 09:02:47 -0700421 //**********************************************************************************************
Ravi Palurif4b38e72020-02-05 12:35:41 +0530422 // Next CAPABILITY value: 0x20000000
Tyler Gunn720c6642016-03-22 09:02:47 -0700423 //**********************************************************************************************
424
425 /**
426 * Indicates that the current device callback number should be shown.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700427 * <p>
428 * Supports Telephony calls where CDMA emergency callback mode is active.
Tyler Gunn720c6642016-03-22 09:02:47 -0700429 * @hide
430 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700431 @SystemApi
Hall Liu25c7c4d2016-08-30 13:41:02 -0700432 public static final int PROPERTY_EMERGENCY_CALLBACK_MODE = 1<<0;
Tyler Gunn720c6642016-03-22 09:02:47 -0700433
434 /**
435 * Whether the call is a generic conference, where we do not know the precise state of
436 * participants in the conference (eg. on CDMA).
Tyler Gunnc63f9082019-10-15 13:19:26 -0700437 * <p>
438 * Supports legacy telephony CDMA calls.
Tyler Gunn720c6642016-03-22 09:02:47 -0700439 * @hide
440 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700441 @SystemApi
Tyler Gunn720c6642016-03-22 09:02:47 -0700442 public static final int PROPERTY_GENERIC_CONFERENCE = 1<<1;
443
444 /**
445 * Connection is using high definition audio.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700446 * <p>
447 * Indicates that the {@link Connection} is using a "high definition" audio codec. This usually
448 * implies something like AMR wideband, but the interpretation of when a call is considered high
449 * definition is left to the {@link ConnectionService} to decide.
450 * <p>
451 * Translates to {@link android.telecom.Call.Details#PROPERTY_HIGH_DEF_AUDIO}.
Tyler Gunn720c6642016-03-22 09:02:47 -0700452 */
453 public static final int PROPERTY_HIGH_DEF_AUDIO = 1<<2;
454
455 /**
456 * Connection is using WIFI.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700457 * <p>
458 * Used to indicate that a call is taking place over WIFI versus a carrier network.
459 * <p>
460 * Translates to {@link android.telecom.Call.Details#PROPERTY_WIFI}.
Tyler Gunn720c6642016-03-22 09:02:47 -0700461 */
462 public static final int PROPERTY_WIFI = 1<<3;
463
464 /**
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700465 * When set, indicates that the {@code Connection} does not actually exist locally for the
466 * {@link ConnectionService}.
467 * <p>
468 * Consider, for example, a scenario where a user has two devices with the same phone number.
469 * When a user places a call on one devices, the telephony stack can represent that call on the
470 * other device by adding is to the {@link ConnectionService} with the
Tyler Gunn720c6642016-03-22 09:02:47 -0700471 * {@link #PROPERTY_IS_EXTERNAL_CALL} capability set.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700472 * <p>
473 * An {@link ConnectionService} should not assume that all {@link InCallService}s will handle
474 * external connections. Only those {@link InCallService}s which have the
475 * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true} in its
476 * manifest will see external connections.
477 */
Tyler Gunn720c6642016-03-22 09:02:47 -0700478 public static final int PROPERTY_IS_EXTERNAL_CALL = 1<<4;
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700479
Brad Ebinger15847072016-05-18 11:08:36 -0700480 /**
481 * Indicates that the connection has CDMA Enhanced Voice Privacy enabled.
482 */
483 public static final int PROPERTY_HAS_CDMA_VOICE_PRIVACY = 1<<5;
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700484
Hall Liu9f332c72016-07-14 15:37:37 -0700485 /**
486 * Indicates that the connection represents a downgraded IMS conference.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700487 * <p>
488 * This property is set when an IMS conference undergoes SRVCC and is re-added to Telecom as a
489 * new entity to indicate that the new connection was a conference.
Hall Liu9f332c72016-07-14 15:37:37 -0700490 * @hide
491 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700492 @SystemApi
Hall Liu9f332c72016-07-14 15:37:37 -0700493 public static final int PROPERTY_IS_DOWNGRADED_CONFERENCE = 1<<6;
494
Tyler Gunnf5035432017-01-09 09:43:12 -0800495 /**
496 * Set by the framework to indicate that the {@link Connection} originated from a self-managed
497 * {@link ConnectionService}.
498 * <p>
499 * See {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.
500 */
501 public static final int PROPERTY_SELF_MANAGED = 1<<7;
502
Hall Liu95d55872017-01-25 17:12:49 -0800503 /**
Hall Liuffa4a812017-03-02 16:11:00 -0800504 * Set by the framework to indicate that a connection has an active RTT session associated with
505 * it.
Hall Liu95d55872017-01-25 17:12:49 -0800506 */
507 public static final int PROPERTY_IS_RTT = 1 << 8;
508
Eric Erfanian62706c52017-12-06 16:27:53 -0800509 /**
510 * Set by the framework to indicate that a connection is using assisted dialing.
Tyler Gunn5567d742019-10-31 13:04:37 -0700511 * <p>
512 * This is used for outgoing calls.
513 *
514 * @see TelecomManager#EXTRA_USE_ASSISTED_DIALING
Eric Erfanian62706c52017-12-06 16:27:53 -0800515 */
Tyler Gunnc9503d62020-01-27 10:30:51 -0800516 public static final int PROPERTY_ASSISTED_DIALING = 1 << 9;
Eric Erfanian62706c52017-12-06 16:27:53 -0800517
Tyler Gunn5bd90852018-09-21 09:37:07 -0700518 /**
519 * Set by the framework to indicate that the network has identified a Connection as an emergency
520 * call.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700521 * <p>
522 * This is used for incoming (mobile-terminated) calls to indicate the call is from emergency
523 * services.
Tyler Gunn5bd90852018-09-21 09:37:07 -0700524 */
525 public static final int PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL = 1 << 10;
526
Tyler Gunnac60f952019-05-31 07:23:16 -0700527 /**
528 * Set by the framework to indicate that a Conference or Connection is hosted by a device other
529 * than the current one. Used in scenarios where the conference originator is the remote device
530 * and the current device is a participant of that conference.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700531 * <p>
532 * This property is specific to IMS conference calls originating in Telephony.
Tyler Gunnac60f952019-05-31 07:23:16 -0700533 * @hide
534 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700535 @SystemApi
Tyler Gunnac60f952019-05-31 07:23:16 -0700536 public static final int PROPERTY_REMOTELY_HOSTED = 1 << 11;
537
Ravi Paluri80aa2142019-12-02 11:57:37 +0530538 /**
Grace Jia8587ee52020-07-10 15:42:32 -0700539 * Set by the framework to indicate that a call is an adhoc conference call.
Ravi Paluri80aa2142019-12-02 11:57:37 +0530540 * <p>
Grace Jia8587ee52020-07-10 15:42:32 -0700541 * This is used for outgoing and incoming conference calls.
Ravi Paluri80aa2142019-12-02 11:57:37 +0530542 */
543 public static final int PROPERTY_IS_ADHOC_CONFERENCE = 1 << 12;
544
Sooraj Sasindran64f05b12020-11-18 12:07:10 -0800545 /**
546 * Connection is using cross sim technology.
547 * <p>
548 * Indicates that the {@link Connection} is using a cross sim technology which would
549 * register IMS over internet APN of default data subscription.
550 * <p>
551 */
552 public static final int PROPERTY_CROSS_SIM = 1 << 13;
Ravi Paluri80aa2142019-12-02 11:57:37 +0530553
Tyler Gunn96d6c402015-03-18 12:39:23 -0700554 //**********************************************************************************************
Sooraj Sasindran64f05b12020-11-18 12:07:10 -0800555 // Next PROPERTY value: 1<<14
Tyler Gunn96d6c402015-03-18 12:39:23 -0700556 //**********************************************************************************************
Tyler Gunn068085b2015-02-06 13:56:52 -0800557
Tyler Gunn335ff2e2015-07-30 14:18:33 -0700558 /**
Tyler Gunn1c687622019-12-20 11:08:13 -0800559 * Indicates that the audio codec is currently not specified or is unknown.
allenwtsu2aca9892019-11-25 14:38:21 +0800560 */
allenwtsu2aca9892019-11-25 14:38:21 +0800561 public static final int AUDIO_CODEC_NONE = ImsStreamMediaProfile.AUDIO_QUALITY_NONE; // 0
Tyler Gunn1c687622019-12-20 11:08:13 -0800562 /**
563 * Adaptive Multi-rate audio codec.
564 */
allenwtsu2aca9892019-11-25 14:38:21 +0800565 public static final int AUDIO_CODEC_AMR = ImsStreamMediaProfile.AUDIO_QUALITY_AMR; // 1
Tyler Gunn1c687622019-12-20 11:08:13 -0800566 /**
567 * Adaptive Multi-rate wideband audio codec.
568 */
allenwtsu2aca9892019-11-25 14:38:21 +0800569 public static final int AUDIO_CODEC_AMR_WB = ImsStreamMediaProfile.AUDIO_QUALITY_AMR_WB; // 2
Tyler Gunn1c687622019-12-20 11:08:13 -0800570 /**
571 * Qualcomm code-excited linear prediction 13 kilobit audio codec.
572 */
allenwtsu2aca9892019-11-25 14:38:21 +0800573 public static final int AUDIO_CODEC_QCELP13K = ImsStreamMediaProfile.AUDIO_QUALITY_QCELP13K; //3
Tyler Gunn1c687622019-12-20 11:08:13 -0800574 /**
575 * Enhanced Variable Rate Codec. See 3GPP2 C.S0014-A.
576 */
allenwtsu2aca9892019-11-25 14:38:21 +0800577 public static final int AUDIO_CODEC_EVRC = ImsStreamMediaProfile.AUDIO_QUALITY_EVRC; // 4
Tyler Gunn1c687622019-12-20 11:08:13 -0800578 /**
579 * Enhanced Variable Rate Codec B. Commonly used on CDMA networks.
580 */
allenwtsu2aca9892019-11-25 14:38:21 +0800581 public static final int AUDIO_CODEC_EVRC_B = ImsStreamMediaProfile.AUDIO_QUALITY_EVRC_B; // 5
Tyler Gunn1c687622019-12-20 11:08:13 -0800582 /**
583 * Enhanced Variable Rate Wideband Codec. See RFC5188.
584 */
allenwtsu2aca9892019-11-25 14:38:21 +0800585 public static final int AUDIO_CODEC_EVRC_WB = ImsStreamMediaProfile.AUDIO_QUALITY_EVRC_WB; // 6
Tyler Gunn1c687622019-12-20 11:08:13 -0800586 /**
587 * Enhanced Variable Rate Narrowband-Wideband Codec.
588 */
allenwtsu2aca9892019-11-25 14:38:21 +0800589 public static final int AUDIO_CODEC_EVRC_NW = ImsStreamMediaProfile.AUDIO_QUALITY_EVRC_NW; // 7
Tyler Gunn1c687622019-12-20 11:08:13 -0800590 /**
591 * GSM Enhanced Full-Rate audio codec, also known as GSM-EFR, GSM 06.60, or simply EFR.
592 */
allenwtsu2aca9892019-11-25 14:38:21 +0800593 public static final int AUDIO_CODEC_GSM_EFR = ImsStreamMediaProfile.AUDIO_QUALITY_GSM_EFR; // 8
Tyler Gunn1c687622019-12-20 11:08:13 -0800594 /**
595 * GSM Full-Rate audio codec, also known as GSM-FR, GSM 06.10, GSM, or simply FR.
596 */
allenwtsu2aca9892019-11-25 14:38:21 +0800597 public static final int AUDIO_CODEC_GSM_FR = ImsStreamMediaProfile.AUDIO_QUALITY_GSM_FR; // 9
Tyler Gunn1c687622019-12-20 11:08:13 -0800598 /**
599 * GSM Half Rate audio codec.
600 */
allenwtsu2aca9892019-11-25 14:38:21 +0800601 public static final int AUDIO_CODEC_GSM_HR = ImsStreamMediaProfile.AUDIO_QUALITY_GSM_HR; // 10
Tyler Gunn1c687622019-12-20 11:08:13 -0800602 /**
603 * ITU-T G711U audio codec.
604 */
allenwtsu2aca9892019-11-25 14:38:21 +0800605 public static final int AUDIO_CODEC_G711U = ImsStreamMediaProfile.AUDIO_QUALITY_G711U; // 11
Tyler Gunn1c687622019-12-20 11:08:13 -0800606 /**
607 * ITU-T G723 audio codec.
608 */
allenwtsu2aca9892019-11-25 14:38:21 +0800609 public static final int AUDIO_CODEC_G723 = ImsStreamMediaProfile.AUDIO_QUALITY_G723; // 12
Tyler Gunn1c687622019-12-20 11:08:13 -0800610 /**
611 * ITU-T G711A audio codec.
612 */
allenwtsu2aca9892019-11-25 14:38:21 +0800613 public static final int AUDIO_CODEC_G711A = ImsStreamMediaProfile.AUDIO_QUALITY_G711A; // 13
Tyler Gunn1c687622019-12-20 11:08:13 -0800614 /**
615 * ITU-T G722 audio codec.
616 */
allenwtsu2aca9892019-11-25 14:38:21 +0800617 public static final int AUDIO_CODEC_G722 = ImsStreamMediaProfile.AUDIO_QUALITY_G722; // 14
Tyler Gunn1c687622019-12-20 11:08:13 -0800618 /**
619 * ITU-T G711AB audio codec.
620 */
allenwtsu2aca9892019-11-25 14:38:21 +0800621 public static final int AUDIO_CODEC_G711AB = ImsStreamMediaProfile.AUDIO_QUALITY_G711AB; // 15
Tyler Gunn1c687622019-12-20 11:08:13 -0800622 /**
623 * ITU-T G729 audio codec.
624 */
allenwtsu2aca9892019-11-25 14:38:21 +0800625 public static final int AUDIO_CODEC_G729 = ImsStreamMediaProfile.AUDIO_QUALITY_G729; // 16
Tyler Gunn1c687622019-12-20 11:08:13 -0800626 /**
627 * Enhanced Voice Services Narrowband audio codec. See 3GPP TS 26.441.
628 */
allenwtsu2aca9892019-11-25 14:38:21 +0800629 public static final int AUDIO_CODEC_EVS_NB = ImsStreamMediaProfile.AUDIO_QUALITY_EVS_NB; // 17
Tyler Gunn1c687622019-12-20 11:08:13 -0800630 /**
631 * Enhanced Voice Services Wideband audio codec. See 3GPP TS 26.441.
632 */
allenwtsu2aca9892019-11-25 14:38:21 +0800633 public static final int AUDIO_CODEC_EVS_WB = ImsStreamMediaProfile.AUDIO_QUALITY_EVS_WB; // 18
Tyler Gunn1c687622019-12-20 11:08:13 -0800634 /**
635 * Enhanced Voice Services Super-Wideband audio codec. See 3GPP TS 26.441.
636 */
allenwtsu2aca9892019-11-25 14:38:21 +0800637 public static final int AUDIO_CODEC_EVS_SWB = ImsStreamMediaProfile.AUDIO_QUALITY_EVS_SWB; // 19
Tyler Gunn1c687622019-12-20 11:08:13 -0800638 /**
639 * Enhanced Voice Services Fullband audio codec. See 3GPP TS 26.441.
640 */
allenwtsu2aca9892019-11-25 14:38:21 +0800641 public static final int AUDIO_CODEC_EVS_FB = ImsStreamMediaProfile.AUDIO_QUALITY_EVS_FB; // 20
642
Tyler Gunn1c687622019-12-20 11:08:13 -0800643 /**@hide*/
644 @Retention(RetentionPolicy.SOURCE)
645 @IntDef(prefix = "AUDIO_CODEC_", value = {
646 AUDIO_CODEC_NONE,
647 AUDIO_CODEC_AMR,
648 AUDIO_CODEC_AMR_WB,
649 AUDIO_CODEC_QCELP13K,
650 AUDIO_CODEC_EVRC,
651 AUDIO_CODEC_EVRC_B,
652 AUDIO_CODEC_EVRC_WB,
653 AUDIO_CODEC_EVRC_NW,
654 AUDIO_CODEC_GSM_EFR,
655 AUDIO_CODEC_GSM_FR,
656 AUDIO_CODEC_GSM_HR,
657 AUDIO_CODEC_G711U,
658 AUDIO_CODEC_G723,
659 AUDIO_CODEC_G711A,
660 AUDIO_CODEC_G722,
661 AUDIO_CODEC_G711AB,
662 AUDIO_CODEC_G729,
663 AUDIO_CODEC_EVS_NB,
664 AUDIO_CODEC_EVS_SWB,
665 AUDIO_CODEC_EVS_FB
666 })
667 public @interface AudioCodec {}
668
allenwtsu2aca9892019-11-25 14:38:21 +0800669 /**
Tyler Gunn335ff2e2015-07-30 14:18:33 -0700670 * Connection extra key used to store the last forwarded number associated with the current
671 * connection. Used to communicate to the user interface that the connection was forwarded via
672 * the specified number.
673 */
674 public static final String EXTRA_LAST_FORWARDED_NUMBER =
675 "android.telecom.extra.LAST_FORWARDED_NUMBER";
676
677 /**
678 * Connection extra key used to store a child number associated with the current connection.
679 * Used to communicate to the user interface that the connection was received via
680 * a child address (i.e. phone number) associated with the {@link PhoneAccount}'s primary
681 * address.
682 */
683 public static final String EXTRA_CHILD_ADDRESS = "android.telecom.extra.CHILD_ADDRESS";
684
685 /**
686 * Connection extra key used to store the subject for an incoming call. The user interface can
687 * query this extra and display its contents for incoming calls. Will only be used if the
688 * {@link PhoneAccount} supports the capability {@link PhoneAccount#CAPABILITY_CALL_SUBJECT}.
689 */
690 public static final String EXTRA_CALL_SUBJECT = "android.telecom.extra.CALL_SUBJECT";
691
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -0800692 /**
Tyler Gunn4b6614e2016-06-22 10:35:13 -0700693 * Boolean connection extra key set on a {@link Connection} in
694 * {@link Connection#STATE_RINGING} state to indicate that answering the call will cause the
695 * current active foreground call to be dropped.
696 */
697 public static final String EXTRA_ANSWERING_DROPS_FG_CALL =
698 "android.telecom.extra.ANSWERING_DROPS_FG_CALL";
699
700 /**
Tyler Gunn37653562017-03-13 18:15:15 -0700701 * String connection extra key set on a {@link Connection} in {@link Connection#STATE_RINGING}
702 * state to indicate the name of the third-party app which is responsible for the current
703 * foreground call.
704 * <p>
705 * Used when {@link #EXTRA_ANSWERING_DROPS_FG_CALL} is true to ensure that the default Phone app
706 * is able to inform the user that answering the new incoming call will cause a call owned by
707 * another app to be dropped when the incoming call is answered.
708 */
709 public static final String EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME =
710 "android.telecom.extra.ANSWERING_DROPS_FG_CALL_APP_NAME";
711
712 /**
Hall Liu10208662016-06-15 17:55:00 -0700713 * Boolean connection extra key on a {@link Connection} which indicates that adding an
Hall Liuee6e86b2016-07-06 16:32:43 -0700714 * additional call is disallowed.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700715 * <p>
716 * Used for mobile-network calls to identify scenarios where carrier requirements preclude
717 * adding another call at the current time.
Hall Liu10208662016-06-15 17:55:00 -0700718 * @hide
719 */
Tyler Gunnc63f9082019-10-15 13:19:26 -0700720 @SystemApi
Hall Liuee6e86b2016-07-06 16:32:43 -0700721 public static final String EXTRA_DISABLE_ADD_CALL =
722 "android.telecom.extra.DISABLE_ADD_CALL";
Hall Liu10208662016-06-15 17:55:00 -0700723
724 /**
Tyler Gunncd6ccfd2016-10-17 15:48:19 -0700725 * String connection extra key on a {@link Connection} or {@link Conference} which contains the
726 * original Connection ID associated with the connection. Used in
727 * {@link RemoteConnectionService} to track the Connection ID which was originally assigned to a
728 * connection/conference added via
729 * {@link ConnectionService#addExistingConnection(PhoneAccountHandle, Connection)} and
730 * {@link ConnectionService#addConference(Conference)} APIs. This is important to pass to
731 * Telecom for when it deals with RemoteConnections. When the ConnectionManager wraps the
732 * {@link RemoteConnection} and {@link RemoteConference} and adds it to Telecom, there needs to
733 * be a way to ensure that we don't add the connection again as a duplicate.
734 * <p>
735 * For example, the TelephonyCS calls addExistingConnection for a Connection with ID
736 * {@code TelephonyCS@1}. The ConnectionManager learns of this via
737 * {@link ConnectionService#onRemoteExistingConnectionAdded(RemoteConnection)}, and wraps this
738 * in a new {@link Connection} which it adds to Telecom via
739 * {@link ConnectionService#addExistingConnection(PhoneAccountHandle, Connection)}. As part of
740 * this process, the wrapped RemoteConnection gets assigned a new ID (e.g. {@code ConnMan@1}).
741 * The TelephonyCS will ALSO try to add the existing connection to Telecom, except with the
742 * ID it originally referred to the connection as. Thus Telecom needs to know that the
743 * Connection with ID {@code ConnMan@1} is really the same as {@code TelephonyCS@1}.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700744 * <p>
745 * This is an internal Telecom framework concept and is not exposed outside of the Telecom
746 * framework.
Tyler Gunncd6ccfd2016-10-17 15:48:19 -0700747 * @hide
748 */
749 public static final String EXTRA_ORIGINAL_CONNECTION_ID =
750 "android.telecom.extra.ORIGINAL_CONNECTION_ID";
751
752 /**
Tyler Gunnc59fd0c2020-04-17 14:03:35 -0700753 * Extra key set on a {@link Connection} when it was created via a remote connection service.
754 * For example, if a connection manager requests a remote connection service to create a call
755 * using one of the remote connection service's phone account handle, this extra will be set so
756 * that Telecom knows that the wrapped remote connection originated in a remote connection
757 * service. We stash this in the extras since connection managers will typically copy the
758 * extras from a {@link RemoteConnection} to a {@link Connection} (there is ultimately not
759 * other way to relate a {@link RemoteConnection} to a {@link Connection}.
760 * @hide
761 */
762 public static final String EXTRA_REMOTE_PHONE_ACCOUNT_HANDLE =
763 "android.telecom.extra.REMOTE_PHONE_ACCOUNT_HANDLE";
764
765 /**
766 * Extra key set from a {@link ConnectionService} when using the remote connection APIs
767 * (e.g. {@link RemoteConnectionService#createRemoteConnection(PhoneAccountHandle,
768 * ConnectionRequest, boolean)}) to create a remote connection. Provides the receiving
769 * {@link ConnectionService} with a means to know the package name of the requesting
770 * {@link ConnectionService} so that {@link #EXTRA_REMOTE_PHONE_ACCOUNT_HANDLE} can be set for
771 * better visibility in Telecom of where a connection ultimately originated.
772 * @hide
773 */
774 public static final String EXTRA_REMOTE_CONNECTION_ORIGINATING_PACKAGE_NAME =
775 "android.telecom.extra.REMOTE_CONNECTION_ORIGINATING_PACKAGE_NAME";
776
777 /**
Wileen Chiuf2ec2982018-07-01 14:21:50 -0700778 * Boolean connection extra key set on the extras passed to
779 * {@link Connection#sendConnectionEvent} which indicates that audio is present
780 * on the RTT call when the extra value is true.
781 */
782 public static final String EXTRA_IS_RTT_AUDIO_PRESENT =
783 "android.telecom.extra.IS_RTT_AUDIO_PRESENT";
784
785 /**
Tyler Gunn1c687622019-12-20 11:08:13 -0800786 * The audio codec in use for the current {@link Connection}, if known. Examples of valid
787 * values include {@link #AUDIO_CODEC_AMR_WB} and {@link #AUDIO_CODEC_EVS_WB}.
allenwtsu2aca9892019-11-25 14:38:21 +0800788 */
Tyler Gunn1c687622019-12-20 11:08:13 -0800789 public static final @AudioCodec String EXTRA_AUDIO_CODEC =
allenwtsu2aca9892019-11-25 14:38:21 +0800790 "android.telecom.extra.AUDIO_CODEC";
791
792 /**
allenwtsu6ec972a2020-11-10 17:32:46 +0800793 * Float connection extra key used to store the audio codec bitrate in kbps for the current
794 * {@link Connection}.
795 */
796 public static final String EXTRA_AUDIO_CODEC_BITRATE_KBPS =
797 "android.telecom.extra.AUDIO_CODEC_BITRATE_KBPS";
798
799 /**
800 * Float connection extra key used to store the audio codec bandwidth in khz for the current
801 * {@link Connection}.
802 */
803 public static final String EXTRA_AUDIO_CODEC_BANDWIDTH_KHZ =
804 "android.telecom.extra.AUDIO_CODEC_BANDWIDTH_KHZ";
805 /**
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -0800806 * Connection event used to inform Telecom that it should play the on hold tone. This is used
807 * to play a tone when the peer puts the current call on hold. Sent to Telecom via
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -0700808 * {@link #sendConnectionEvent(String, Bundle)}.
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -0800809 */
810 public static final String EVENT_ON_HOLD_TONE_START =
811 "android.telecom.event.ON_HOLD_TONE_START";
812
813 /**
814 * Connection event used to inform Telecom that it should stop the on hold tone. This is used
815 * to stop a tone when the peer puts the current call on hold. Sent to Telecom via
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -0700816 * {@link #sendConnectionEvent(String, Bundle)}.
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -0800817 */
818 public static final String EVENT_ON_HOLD_TONE_END =
819 "android.telecom.event.ON_HOLD_TONE_END";
820
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700821 /**
822 * Connection event used to inform {@link InCallService}s when pulling of an external call has
823 * failed. The user interface should inform the user of the error.
824 * <p>
825 * Expected to be used by the {@link ConnectionService} when the {@link Call#pullExternalCall()}
826 * API is called on a {@link Call} with the properties
827 * {@link Call.Details#PROPERTY_IS_EXTERNAL_CALL} and
828 * {@link Call.Details#CAPABILITY_CAN_PULL_CALL}, but the {@link ConnectionService} could not
829 * pull the external call due to an error condition.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -0700830 * <p>
831 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
832 * expected to be null when this connection event is used.
Tyler Gunn876dbfb2016-03-14 15:18:07 -0700833 */
834 public static final String EVENT_CALL_PULL_FAILED = "android.telecom.event.CALL_PULL_FAILED";
835
Brad Ebinger2c1c16452016-05-27 15:58:10 -0700836 /**
837 * Connection event used to inform {@link InCallService}s when the merging of two calls has
838 * failed. The User Interface should use this message to inform the user of the error.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -0700839 * <p>
840 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
841 * expected to be null when this connection event is used.
Brad Ebinger2c1c16452016-05-27 15:58:10 -0700842 */
843 public static final String EVENT_CALL_MERGE_FAILED = "android.telecom.event.CALL_MERGE_FAILED";
844
Tyler Gunnb5ed8602016-08-17 13:48:27 -0700845 /**
Hall Liu06ae75b2019-03-11 19:11:35 -0700846 * Connection event used to inform Telecom when a hold operation on a call has failed.
Tyler Gunnc63f9082019-10-15 13:19:26 -0700847 * <p>
Hall Liu06ae75b2019-03-11 19:11:35 -0700848 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
849 * expected to be null when this connection event is used.
Hall Liu06ae75b2019-03-11 19:11:35 -0700850 */
851 public static final String EVENT_CALL_HOLD_FAILED = "android.telecom.event.CALL_HOLD_FAILED";
852
853 /**
Masaho Nishikawacb8fa742019-11-07 14:41:21 +0900854 * Connection event used to inform Telecom when a switch operation on a call has failed.
855 * <p>
856 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
857 * expected to be null when this connection event is used.
858 */
859 public static final String EVENT_CALL_SWITCH_FAILED =
860 "android.telecom.event.CALL_SWITCH_FAILED";
861
862 /**
Tyler Gunn78da7812017-05-09 14:34:57 -0700863 * Connection event used to inform {@link InCallService}s when the process of merging a
864 * Connection into a conference has begun.
865 * <p>
866 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
867 * expected to be null when this connection event is used.
Tyler Gunn78da7812017-05-09 14:34:57 -0700868 */
869 public static final String EVENT_MERGE_START = "android.telecom.event.MERGE_START";
870
871 /**
872 * Connection event used to inform {@link InCallService}s when the process of merging a
873 * Connection into a conference has completed.
874 * <p>
875 * Sent via {@link #sendConnectionEvent(String, Bundle)}. The {@link Bundle} parameter is
876 * expected to be null when this connection event is used.
Tyler Gunn78da7812017-05-09 14:34:57 -0700877 */
878 public static final String EVENT_MERGE_COMPLETE = "android.telecom.event.MERGE_COMPLETE";
879
880 /**
Tyler Gunnb5ed8602016-08-17 13:48:27 -0700881 * Connection event used to inform {@link InCallService}s when a call has been put on hold by
882 * the remote party.
883 * <p>
884 * This is different than the {@link Connection#STATE_HOLDING} state which indicates that the
885 * call is being held locally on the device. When a capable {@link ConnectionService} receives
886 * signalling to indicate that the remote party has put the call on hold, it can send this
887 * connection event.
Tyler Gunnb5ed8602016-08-17 13:48:27 -0700888 */
889 public static final String EVENT_CALL_REMOTELY_HELD =
890 "android.telecom.event.CALL_REMOTELY_HELD";
891
892 /**
893 * Connection event used to inform {@link InCallService}s when a call which was remotely held
894 * (see {@link #EVENT_CALL_REMOTELY_HELD}) has been un-held by the remote party.
895 * <p>
896 * This is different than the {@link Connection#STATE_HOLDING} state which indicates that the
897 * call is being held locally on the device. When a capable {@link ConnectionService} receives
898 * signalling to indicate that the remote party has taken the call off hold, it can send this
899 * connection event.
Tyler Gunnb5ed8602016-08-17 13:48:27 -0700900 */
901 public static final String EVENT_CALL_REMOTELY_UNHELD =
902 "android.telecom.event.CALL_REMOTELY_UNHELD";
903
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700904 /**
905 * Connection event used to inform an {@link InCallService} which initiated a call handover via
906 * {@link Call#EVENT_REQUEST_HANDOVER} that the handover from this {@link Connection} has
907 * successfully completed.
908 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700909 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
910 * APIs instead.
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700911 */
912 public static final String EVENT_HANDOVER_COMPLETE =
913 "android.telecom.event.HANDOVER_COMPLETE";
914
915 /**
916 * Connection event used to inform an {@link InCallService} which initiated a call handover via
917 * {@link Call#EVENT_REQUEST_HANDOVER} that the handover from this {@link Connection} has failed
918 * to complete.
919 * @hide
Tyler Gunn1a505fa2018-09-14 13:36:38 -0700920 * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
921 * APIs instead.
Tyler Gunn9f6f0472017-04-17 18:25:22 -0700922 */
923 public static final String EVENT_HANDOVER_FAILED =
924 "android.telecom.event.HANDOVER_FAILED";
925
shilub7ec9a02018-11-09 15:52:04 -0800926 /**
Shi Lu528eb5b2019-02-08 05:09:11 +0000927 * String Connection extra key used to store SIP invite fields for an incoming call for IMS call
shilub7ec9a02018-11-09 15:52:04 -0800928 */
929 public static final String EXTRA_SIP_INVITE = "android.telecom.extra.SIP_INVITE";
930
Wileen Chiuf2ec2982018-07-01 14:21:50 -0700931 /**
932 * Connection event used to inform an {@link InCallService} that the RTT audio indication
933 * has changed.
934 */
935 public static final String EVENT_RTT_AUDIO_INDICATION_CHANGED =
936 "android.telecom.event.RTT_AUDIO_INDICATION_CHANGED";
937
Ihab Awadb19a0bc2014-08-07 19:46:01 -0700938 // Flag controlling whether PII is emitted into the logs
939 private static final boolean PII_DEBUG = Log.isLoggable(android.util.Log.DEBUG);
940
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800941 /**
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -0700942 * Renders a set of capability bits ({@code CAPABILITY_*}) as a human readable string.
943 *
944 * @param capabilities A capability bit field.
945 * @return A human readable string representation.
946 */
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800947 public static String capabilitiesToString(int capabilities) {
Santos Cordon1a749302016-07-26 16:08:53 -0700948 return capabilitiesToStringInternal(capabilities, true /* isLong */);
949 }
950
951 /**
952 * Renders a set of capability bits ({@code CAPABILITY_*}) as a *short* human readable
953 * string.
954 *
955 * @param capabilities A capability bit field.
956 * @return A human readable string representation.
957 * @hide
958 */
959 public static String capabilitiesToStringShort(int capabilities) {
960 return capabilitiesToStringInternal(capabilities, false /* isLong */);
961 }
962
963 private static String capabilitiesToStringInternal(int capabilities, boolean isLong) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800964 StringBuilder builder = new StringBuilder();
Santos Cordon1a749302016-07-26 16:08:53 -0700965 builder.append("[");
966 if (isLong) {
967 builder.append("Capabilities:");
968 }
969
Tyler Gunnc63f9082019-10-15 13:19:26 -0700970 if ((capabilities & CAPABILITY_HOLD) == CAPABILITY_HOLD) {
Santos Cordon1a749302016-07-26 16:08:53 -0700971 builder.append(isLong ? " CAPABILITY_HOLD" : " hld");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800972 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700973 if ((capabilities & CAPABILITY_SUPPORT_HOLD) == CAPABILITY_SUPPORT_HOLD) {
Santos Cordon1a749302016-07-26 16:08:53 -0700974 builder.append(isLong ? " CAPABILITY_SUPPORT_HOLD" : " sup_hld");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800975 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700976 if ((capabilities & CAPABILITY_MERGE_CONFERENCE) == CAPABILITY_MERGE_CONFERENCE) {
Santos Cordon1a749302016-07-26 16:08:53 -0700977 builder.append(isLong ? " CAPABILITY_MERGE_CONFERENCE" : " mrg_cnf");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800978 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700979 if ((capabilities & CAPABILITY_SWAP_CONFERENCE) == CAPABILITY_SWAP_CONFERENCE) {
Santos Cordon1a749302016-07-26 16:08:53 -0700980 builder.append(isLong ? " CAPABILITY_SWAP_CONFERENCE" : " swp_cnf");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800981 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700982 if ((capabilities & CAPABILITY_RESPOND_VIA_TEXT) == CAPABILITY_RESPOND_VIA_TEXT) {
Santos Cordon1a749302016-07-26 16:08:53 -0700983 builder.append(isLong ? " CAPABILITY_RESPOND_VIA_TEXT" : " txt");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800984 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700985 if ((capabilities & CAPABILITY_MUTE) == CAPABILITY_MUTE) {
Santos Cordon1a749302016-07-26 16:08:53 -0700986 builder.append(isLong ? " CAPABILITY_MUTE" : " mut");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800987 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700988 if ((capabilities & CAPABILITY_MANAGE_CONFERENCE) == CAPABILITY_MANAGE_CONFERENCE) {
Santos Cordon1a749302016-07-26 16:08:53 -0700989 builder.append(isLong ? " CAPABILITY_MANAGE_CONFERENCE" : " mng_cnf");
Ihab Awad5c9c86e2014-11-12 13:41:16 -0800990 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700991 if ((capabilities & CAPABILITY_SUPPORTS_VT_LOCAL_RX) == CAPABILITY_SUPPORTS_VT_LOCAL_RX) {
Santos Cordon1a749302016-07-26 16:08:53 -0700992 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_RX" : " VTlrx");
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700993 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700994 if ((capabilities & CAPABILITY_SUPPORTS_VT_LOCAL_TX) == CAPABILITY_SUPPORTS_VT_LOCAL_TX) {
Santos Cordon1a749302016-07-26 16:08:53 -0700995 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_TX" : " VTltx");
Andrew Lee5e9e8bb2015-03-10 13:58:24 -0700996 }
Tyler Gunnc63f9082019-10-15 13:19:26 -0700997 if ((capabilities & CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL)
998 == CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL) {
Santos Cordon1a749302016-07-26 16:08:53 -0700999 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL" : " VTlbi");
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001000 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001001 if ((capabilities & CAPABILITY_SUPPORTS_VT_REMOTE_RX) == CAPABILITY_SUPPORTS_VT_REMOTE_RX) {
Santos Cordon1a749302016-07-26 16:08:53 -07001002 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_RX" : " VTrrx");
Andrew Lee5e9e8bb2015-03-10 13:58:24 -07001003 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001004 if ((capabilities & CAPABILITY_SUPPORTS_VT_REMOTE_TX) == CAPABILITY_SUPPORTS_VT_REMOTE_TX) {
Santos Cordon1a749302016-07-26 16:08:53 -07001005 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_TX" : " VTrtx");
Andrew Lee5e9e8bb2015-03-10 13:58:24 -07001006 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001007 if ((capabilities & CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL)
1008 == CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL) {
Santos Cordon1a749302016-07-26 16:08:53 -07001009 builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL" : " VTrbi");
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001010 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001011 if ((capabilities & CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO)
1012 == CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO) {
Santos Cordon1a749302016-07-26 16:08:53 -07001013 builder.append(isLong ? " CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO" : " !v2a");
Tyler Gunnf97a0092016-01-19 15:59:34 -08001014 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001015 if ((capabilities & CAPABILITY_SPEED_UP_MT_AUDIO) == CAPABILITY_SPEED_UP_MT_AUDIO) {
Santos Cordon1a749302016-07-26 16:08:53 -07001016 builder.append(isLong ? " CAPABILITY_SPEED_UP_MT_AUDIO" : " spd_aud");
Dong Zhou89f41eb2015-03-15 11:59:49 -05001017 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001018 if ((capabilities & CAPABILITY_CAN_UPGRADE_TO_VIDEO) == CAPABILITY_CAN_UPGRADE_TO_VIDEO) {
Santos Cordon1a749302016-07-26 16:08:53 -07001019 builder.append(isLong ? " CAPABILITY_CAN_UPGRADE_TO_VIDEO" : " a2v");
Rekha Kumar07366812015-03-24 16:42:31 -07001020 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001021 if ((capabilities & CAPABILITY_CAN_PAUSE_VIDEO) == CAPABILITY_CAN_PAUSE_VIDEO) {
Santos Cordon1a749302016-07-26 16:08:53 -07001022 builder.append(isLong ? " CAPABILITY_CAN_PAUSE_VIDEO" : " paus_VT");
Tyler Gunnb5e0cfb2015-04-07 16:10:51 -07001023 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001024 if ((capabilities & CAPABILITY_CONFERENCE_HAS_NO_CHILDREN)
1025 == CAPABILITY_CONFERENCE_HAS_NO_CHILDREN) {
Santos Cordon1a749302016-07-26 16:08:53 -07001026 builder.append(isLong ? " CAPABILITY_SINGLE_PARTY_CONFERENCE" : " 1p_cnf");
Tyler Gunnd4091732015-06-29 09:15:37 -07001027 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001028 if ((capabilities & CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION)
1029 == CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION) {
Santos Cordon1a749302016-07-26 16:08:53 -07001030 builder.append(isLong ? " CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION" : " rsp_by_con");
Bryce Lee81901682015-08-28 16:38:02 -07001031 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001032 if ((capabilities & CAPABILITY_CAN_PULL_CALL) == CAPABILITY_CAN_PULL_CALL) {
Santos Cordon1a749302016-07-26 16:08:53 -07001033 builder.append(isLong ? " CAPABILITY_CAN_PULL_CALL" : " pull");
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001034 }
Tyler Gunnc63f9082019-10-15 13:19:26 -07001035 if ((capabilities & CAPABILITY_SUPPORT_DEFLECT) == CAPABILITY_SUPPORT_DEFLECT) {
Pooja Jaind34698d2017-12-28 14:15:31 +05301036 builder.append(isLong ? " CAPABILITY_SUPPORT_DEFLECT" : " sup_def");
1037 }
Ravi Paluri404babb2020-01-23 19:02:44 +05301038 if ((capabilities & CAPABILITY_ADD_PARTICIPANT) == CAPABILITY_ADD_PARTICIPANT) {
1039 builder.append(isLong ? " CAPABILITY_ADD_PARTICIPANT" : " add_participant");
1040 }
Ravi Palurif4b38e72020-02-05 12:35:41 +05301041 if ((capabilities & CAPABILITY_TRANSFER) == CAPABILITY_TRANSFER) {
1042 builder.append(isLong ? " CAPABILITY_TRANSFER" : " sup_trans");
1043 }
1044 if ((capabilities & CAPABILITY_TRANSFER_CONSULTATIVE)
1045 == CAPABILITY_TRANSFER_CONSULTATIVE) {
1046 builder.append(isLong ? " CAPABILITY_TRANSFER_CONSULTATIVE" : " sup_cTrans");
1047 }
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001048 builder.append("]");
1049 return builder.toString();
1050 }
1051
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07001052 /**
1053 * Renders a set of property bits ({@code PROPERTY_*}) as a human readable string.
1054 *
1055 * @param properties A property bit field.
1056 * @return A human readable string representation.
1057 */
Tyler Gunn720c6642016-03-22 09:02:47 -07001058 public static String propertiesToString(int properties) {
Santos Cordon1a749302016-07-26 16:08:53 -07001059 return propertiesToStringInternal(properties, true /* isLong */);
1060 }
1061
1062 /**
1063 * Renders a set of property bits ({@code PROPERTY_*}) as a *short* human readable string.
1064 *
1065 * @param properties A property bit field.
1066 * @return A human readable string representation.
1067 * @hide
1068 */
1069 public static String propertiesToStringShort(int properties) {
1070 return propertiesToStringInternal(properties, false /* isLong */);
1071 }
1072
1073 private static String propertiesToStringInternal(int properties, boolean isLong) {
Tyler Gunn720c6642016-03-22 09:02:47 -07001074 StringBuilder builder = new StringBuilder();
Santos Cordon1a749302016-07-26 16:08:53 -07001075 builder.append("[");
1076 if (isLong) {
1077 builder.append("Properties:");
1078 }
Tyler Gunn720c6642016-03-22 09:02:47 -07001079
Tyler Gunnc63f9082019-10-15 13:19:26 -07001080 if ((properties & PROPERTY_SELF_MANAGED) == PROPERTY_SELF_MANAGED) {
Tyler Gunnf5035432017-01-09 09:43:12 -08001081 builder.append(isLong ? " PROPERTY_SELF_MANAGED" : " self_mng");
1082 }
1083
Tyler Gunnc63f9082019-10-15 13:19:26 -07001084 if ((properties & PROPERTY_EMERGENCY_CALLBACK_MODE) == PROPERTY_EMERGENCY_CALLBACK_MODE) {
Hall Liu25c7c4d2016-08-30 13:41:02 -07001085 builder.append(isLong ? " PROPERTY_EMERGENCY_CALLBACK_MODE" : " ecbm");
Tyler Gunn720c6642016-03-22 09:02:47 -07001086 }
1087
Tyler Gunnc63f9082019-10-15 13:19:26 -07001088 if ((properties & PROPERTY_HIGH_DEF_AUDIO) == PROPERTY_HIGH_DEF_AUDIO) {
Santos Cordon1a749302016-07-26 16:08:53 -07001089 builder.append(isLong ? " PROPERTY_HIGH_DEF_AUDIO" : " HD");
Tyler Gunn720c6642016-03-22 09:02:47 -07001090 }
1091
Tyler Gunnc63f9082019-10-15 13:19:26 -07001092 if ((properties & PROPERTY_WIFI) == PROPERTY_WIFI) {
Santos Cordon1a749302016-07-26 16:08:53 -07001093 builder.append(isLong ? " PROPERTY_WIFI" : " wifi");
Tyler Gunn720c6642016-03-22 09:02:47 -07001094 }
1095
Tyler Gunnc63f9082019-10-15 13:19:26 -07001096 if ((properties & PROPERTY_GENERIC_CONFERENCE) == PROPERTY_GENERIC_CONFERENCE) {
Santos Cordon1a749302016-07-26 16:08:53 -07001097 builder.append(isLong ? " PROPERTY_GENERIC_CONFERENCE" : " gen_conf");
Tyler Gunn720c6642016-03-22 09:02:47 -07001098 }
1099
Tyler Gunnc63f9082019-10-15 13:19:26 -07001100 if ((properties & PROPERTY_IS_EXTERNAL_CALL) == PROPERTY_IS_EXTERNAL_CALL) {
Santos Cordon1a749302016-07-26 16:08:53 -07001101 builder.append(isLong ? " PROPERTY_IS_EXTERNAL_CALL" : " xtrnl");
Tyler Gunn720c6642016-03-22 09:02:47 -07001102 }
1103
Tyler Gunnc63f9082019-10-15 13:19:26 -07001104 if ((properties & PROPERTY_HAS_CDMA_VOICE_PRIVACY) == PROPERTY_HAS_CDMA_VOICE_PRIVACY) {
Santos Cordon1a749302016-07-26 16:08:53 -07001105 builder.append(isLong ? " PROPERTY_HAS_CDMA_VOICE_PRIVACY" : " priv");
Brad Ebinger15847072016-05-18 11:08:36 -07001106 }
1107
Tyler Gunnc63f9082019-10-15 13:19:26 -07001108 if ((properties & PROPERTY_IS_RTT) == PROPERTY_IS_RTT) {
Hall Liud4d2a8a2018-01-29 17:22:02 -08001109 builder.append(isLong ? " PROPERTY_IS_RTT" : " rtt");
1110 }
1111
Tyler Gunnc63f9082019-10-15 13:19:26 -07001112 if ((properties & PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL)
1113 == PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL) {
Tyler Gunn5bd90852018-09-21 09:37:07 -07001114 builder.append(isLong ? " PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL" : " ecall");
1115 }
1116
Tyler Gunnc63f9082019-10-15 13:19:26 -07001117 if ((properties & PROPERTY_REMOTELY_HOSTED) == PROPERTY_REMOTELY_HOSTED) {
Tyler Gunnac60f952019-05-31 07:23:16 -07001118 builder.append(isLong ? " PROPERTY_REMOTELY_HOSTED" : " remote_hst");
1119 }
1120
Ravi Paluri80aa2142019-12-02 11:57:37 +05301121 if ((properties & PROPERTY_IS_ADHOC_CONFERENCE) == PROPERTY_IS_ADHOC_CONFERENCE) {
1122 builder.append(isLong ? " PROPERTY_IS_ADHOC_CONFERENCE" : " adhoc_conf");
1123 }
1124
Tyler Gunn720c6642016-03-22 09:02:47 -07001125 builder.append("]");
1126 return builder.toString();
1127 }
1128
Sailesh Nepal091768c2014-06-30 15:15:23 -07001129 /** @hide */
Tyler Gunn633e4c32019-10-24 15:40:48 -07001130 abstract static class Listener {
Ihab Awad542e0ea2014-05-16 10:22:16 -07001131 public void onStateChanged(Connection c, int state) {}
Andrew Lee100e2932014-09-08 15:34:24 -07001132 public void onAddressChanged(Connection c, Uri newAddress, int presentation) {}
Sailesh Nepal61203862014-07-11 14:50:13 -07001133 public void onCallerDisplayNameChanged(
1134 Connection c, String callerDisplayName, int presentation) {}
Tyler Gunnaa07df82014-07-17 07:50:22 -07001135 public void onVideoStateChanged(Connection c, int videoState) {}
Andrew Lee7f3d41f2014-09-11 17:33:16 -07001136 public void onDisconnected(Connection c, DisconnectCause disconnectCause) {}
Sailesh Nepal091768c2014-06-30 15:15:23 -07001137 public void onPostDialWait(Connection c, String remaining) {}
Nancy Chen27d1c2d2014-12-15 16:12:50 -08001138 public void onPostDialChar(Connection c, char nextChar) {}
Andrew Lee100e2932014-09-08 15:34:24 -07001139 public void onRingbackRequested(Connection c, boolean ringback) {}
Sailesh Nepal61203862014-07-11 14:50:13 -07001140 public void onDestroyed(Connection c) {}
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001141 public void onConnectionCapabilitiesChanged(Connection c, int capabilities) {}
Tyler Gunn720c6642016-03-22 09:02:47 -07001142 public void onConnectionPropertiesChanged(Connection c, int properties) {}
Christine Hallstrom2830ce92016-11-30 16:06:42 -08001143 public void onSupportedAudioRoutesChanged(Connection c, int supportedAudioRoutes) {}
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001144 public void onVideoProviderChanged(
1145 Connection c, VideoProvider videoProvider) {}
Sailesh Nepal001bbbb2014-07-15 14:40:39 -07001146 public void onAudioModeIsVoipChanged(Connection c, boolean isVoip) {}
1147 public void onStatusHintsChanged(Connection c, StatusHints statusHints) {}
Tyler Gunn6d76ca02014-11-17 15:49:51 -08001148 public void onConferenceablesChanged(
Tyler Gunndf2cbc82015-04-20 09:13:01 -07001149 Connection c, List<Conferenceable> conferenceables) {}
Santos Cordon823fd3c2014-08-07 18:35:18 -07001150 public void onConferenceChanged(Connection c, Conference conference) {}
Anthony Lee17455a32015-04-24 15:25:29 -07001151 public void onConferenceMergeFailed(Connection c) {}
Santos Cordon6b7f9552015-05-27 17:21:45 -07001152 public void onExtrasChanged(Connection c, Bundle extras) {}
Tyler Gunndee56a82016-03-23 16:06:34 -07001153 public void onExtrasRemoved(Connection c, List<String> keys) {}
Tyler Gunn876dbfb2016-03-14 15:18:07 -07001154 public void onConnectionEvent(Connection c, String event, Bundle extras) {}
Hall Liua98f58b52017-11-07 17:59:28 -08001155 public void onAudioRouteChanged(Connection c, int audioRoute, String bluetoothAddress) {}
Hall Liub64ac4c2017-02-06 10:49:48 -08001156 public void onRttInitiationSuccess(Connection c) {}
1157 public void onRttInitiationFailure(Connection c, int reason) {}
1158 public void onRttSessionRemotelyTerminated(Connection c) {}
1159 public void onRemoteRttRequest(Connection c) {}
Srikanth Chintalafcb15012017-05-04 20:58:34 +05301160 /** @hide */
1161 public void onPhoneAccountChanged(Connection c, PhoneAccountHandle pHandle) {}
Mengjun Leng25707742017-07-04 11:10:37 +08001162 public void onConnectionTimeReset(Connection c) {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07001163 }
1164
Tyler Gunnb702ef82015-05-29 11:51:53 -07001165 /**
Hall Liu95d55872017-01-25 17:12:49 -08001166 * Provides methods to read and write RTT data to/from the in-call app.
Hall Liu95d55872017-01-25 17:12:49 -08001167 */
1168 public static final class RttTextStream {
1169 private static final int READ_BUFFER_SIZE = 1000;
1170 private final InputStreamReader mPipeFromInCall;
1171 private final OutputStreamWriter mPipeToInCall;
Hall Liub64ac4c2017-02-06 10:49:48 -08001172 private final ParcelFileDescriptor mFdFromInCall;
1173 private final ParcelFileDescriptor mFdToInCall;
Hall Liu17eb1bd2018-07-03 15:17:41 -07001174
1175 private final FileInputStream mFromInCallFileInputStream;
Hall Liu95d55872017-01-25 17:12:49 -08001176 private char[] mReadBuffer = new char[READ_BUFFER_SIZE];
1177
1178 /**
1179 * @hide
1180 */
1181 public RttTextStream(ParcelFileDescriptor toInCall, ParcelFileDescriptor fromInCall) {
Hall Liub64ac4c2017-02-06 10:49:48 -08001182 mFdFromInCall = fromInCall;
1183 mFdToInCall = toInCall;
Hall Liu17eb1bd2018-07-03 15:17:41 -07001184 mFromInCallFileInputStream = new FileInputStream(fromInCall.getFileDescriptor());
Hall Liu730a2592018-06-25 19:48:33 -07001185
1186 // Wrap the FileInputStream in a Channel so that it's interruptible.
Hall Liu95d55872017-01-25 17:12:49 -08001187 mPipeFromInCall = new InputStreamReader(
Hall Liu17eb1bd2018-07-03 15:17:41 -07001188 Channels.newInputStream(Channels.newChannel(mFromInCallFileInputStream)));
Hall Liu95d55872017-01-25 17:12:49 -08001189 mPipeToInCall = new OutputStreamWriter(
Hall Liua549fed2018-02-09 16:40:03 -08001190 new FileOutputStream(toInCall.getFileDescriptor()));
Hall Liu95d55872017-01-25 17:12:49 -08001191 }
1192
1193 /**
1194 * Writes the string {@param input} into the text stream to the UI for this RTT call. Since
1195 * RTT transmits text in real-time, this method should be called as often as text snippets
1196 * are received from the remote user, even if it is only one character.
Hall Liua549fed2018-02-09 16:40:03 -08001197 * <p>
Hall Liu95d55872017-01-25 17:12:49 -08001198 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1199 * lead to interleaved text.
Hall Liua549fed2018-02-09 16:40:03 -08001200 *
Hall Liu95d55872017-01-25 17:12:49 -08001201 * @param input The message to send to the in-call app.
1202 */
1203 public void write(String input) throws IOException {
1204 mPipeToInCall.write(input);
1205 mPipeToInCall.flush();
1206 }
1207
1208
1209 /**
1210 * Reads a string from the in-call app, blocking if there is no data available. Returns
1211 * {@code null} if the RTT conversation has been terminated and there is no further data
1212 * to read.
Hall Liua549fed2018-02-09 16:40:03 -08001213 * <p>
Hall Liu95d55872017-01-25 17:12:49 -08001214 * This method is not thread-safe -- calling it from multiple threads simultaneously may
1215 * lead to interleaved text.
Hall Liua549fed2018-02-09 16:40:03 -08001216 *
Hall Liu95d55872017-01-25 17:12:49 -08001217 * @return A string containing text entered by the user, or {@code null} if the
1218 * conversation has been terminated or if there was an error while reading.
1219 */
Hall Liuffa4a812017-03-02 16:11:00 -08001220 public String read() throws IOException {
1221 int numRead = mPipeFromInCall.read(mReadBuffer, 0, READ_BUFFER_SIZE);
1222 if (numRead < 0) {
1223 return null;
1224 }
1225 return new String(mReadBuffer, 0, numRead);
1226 }
1227
1228 /**
1229 * Non-blocking version of {@link #read()}. Returns {@code null} if there is nothing to
1230 * be read.
Hall Liua549fed2018-02-09 16:40:03 -08001231 *
Hall Liuffa4a812017-03-02 16:11:00 -08001232 * @return A string containing text entered by the user, or {@code null} if the user has
1233 * not entered any new text yet.
1234 */
1235 public String readImmediately() throws IOException {
Hall Liu17eb1bd2018-07-03 15:17:41 -07001236 if (mFromInCallFileInputStream.available() > 0) {
Hall Liuffa4a812017-03-02 16:11:00 -08001237 return read();
1238 } else {
Hall Liu95d55872017-01-25 17:12:49 -08001239 return null;
1240 }
1241 }
Hall Liub64ac4c2017-02-06 10:49:48 -08001242
1243 /** @hide */
1244 public ParcelFileDescriptor getFdFromInCall() {
1245 return mFdFromInCall;
1246 }
1247
1248 /** @hide */
1249 public ParcelFileDescriptor getFdToInCall() {
1250 return mFdToInCall;
1251 }
1252 }
1253
1254 /**
1255 * Provides constants to represent the results of responses to session modify requests sent via
1256 * {@link Call#sendRttRequest()}
1257 */
1258 public static final class RttModifyStatus {
Hall Liu8dd49082017-04-21 14:33:12 -07001259 private RttModifyStatus() {}
Hall Liub64ac4c2017-02-06 10:49:48 -08001260 /**
1261 * Session modify request was successful.
1262 */
1263 public static final int SESSION_MODIFY_REQUEST_SUCCESS = 1;
1264
1265 /**
1266 * Session modify request failed.
1267 */
1268 public static final int SESSION_MODIFY_REQUEST_FAIL = 2;
1269
1270 /**
1271 * Session modify request ignored due to invalid parameters.
1272 */
1273 public static final int SESSION_MODIFY_REQUEST_INVALID = 3;
1274
1275 /**
1276 * Session modify request timed out.
1277 */
1278 public static final int SESSION_MODIFY_REQUEST_TIMED_OUT = 4;
1279
1280 /**
1281 * Session modify request rejected by remote user.
1282 */
1283 public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE = 5;
Hall Liu95d55872017-01-25 17:12:49 -08001284 }
1285
1286 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001287 * Provides a means of controlling the video session associated with a {@link Connection}.
1288 * <p>
1289 * Implementations create a custom subclass of {@link VideoProvider} and the
1290 * {@link ConnectionService} creates an instance sets it on the {@link Connection} using
1291 * {@link Connection#setVideoProvider(VideoProvider)}. Any connection which supports video
1292 * should set the {@link VideoProvider}.
1293 * <p>
1294 * The {@link VideoProvider} serves two primary purposes: it provides a means for Telecom and
1295 * {@link InCallService} implementations to issue requests related to the video session;
1296 * it provides a means for the {@link ConnectionService} to report events and information
1297 * related to the video session to Telecom and the {@link InCallService} implementations.
1298 * <p>
1299 * {@link InCallService} implementations interact with the {@link VideoProvider} via
1300 * {@link android.telecom.InCallService.VideoCall}.
1301 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001302 public static abstract class VideoProvider {
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001303 /**
1304 * Video is not being received (no protocol pause was issued).
Tyler Gunnb702ef82015-05-29 11:51:53 -07001305 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001306 */
1307 public static final int SESSION_EVENT_RX_PAUSE = 1;
Evan Charltonbf11f982014-07-20 22:06:28 -07001308
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001309 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001310 * Video reception has resumed after a {@link #SESSION_EVENT_RX_PAUSE}.
1311 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001312 */
1313 public static final int SESSION_EVENT_RX_RESUME = 2;
1314
1315 /**
1316 * Video transmission has begun. This occurs after a negotiated start of video transmission
1317 * when the underlying protocol has actually begun transmitting video to the remote party.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001318 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001319 */
1320 public static final int SESSION_EVENT_TX_START = 3;
1321
1322 /**
1323 * Video transmission has stopped. This occurs after a negotiated stop of video transmission
1324 * when the underlying protocol has actually stopped transmitting video to the remote party.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001325 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001326 */
1327 public static final int SESSION_EVENT_TX_STOP = 4;
1328
1329 /**
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001330 * A camera failure has occurred for the selected camera. The {@link VideoProvider} can use
Tyler Gunnb702ef82015-05-29 11:51:53 -07001331 * this as a cue to inform the user the camera is not available.
1332 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001333 */
1334 public static final int SESSION_EVENT_CAMERA_FAILURE = 5;
1335
1336 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001337 * Issued after {@link #SESSION_EVENT_CAMERA_FAILURE} when the camera is once again ready
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001338 * for operation. The {@link VideoProvider} can use this as a cue to inform the user that
Tyler Gunnb702ef82015-05-29 11:51:53 -07001339 * the camera has become available again.
1340 * @see #handleCallSessionEvent(int)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001341 */
1342 public static final int SESSION_EVENT_CAMERA_READY = 6;
1343
1344 /**
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001345 * Session event raised by Telecom when
1346 * {@link android.telecom.InCallService.VideoCall#setCamera(String)} is called and the
1347 * caller does not have the necessary {@link android.Manifest.permission#CAMERA} permission.
1348 * @see #handleCallSessionEvent(int)
1349 */
1350 public static final int SESSION_EVENT_CAMERA_PERMISSION_ERROR = 7;
1351
1352 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001353 * Session modify request was successful.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001354 * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001355 */
1356 public static final int SESSION_MODIFY_REQUEST_SUCCESS = 1;
1357
1358 /**
1359 * Session modify request failed.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001360 * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001361 */
1362 public static final int SESSION_MODIFY_REQUEST_FAIL = 2;
1363
1364 /**
1365 * Session modify request ignored due to invalid parameters.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001366 * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001367 */
1368 public static final int SESSION_MODIFY_REQUEST_INVALID = 3;
1369
Rekha Kumar07366812015-03-24 16:42:31 -07001370 /**
1371 * Session modify request timed out.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001372 * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
Rekha Kumar07366812015-03-24 16:42:31 -07001373 */
1374 public static final int SESSION_MODIFY_REQUEST_TIMED_OUT = 4;
1375
1376 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001377 * Session modify request rejected by remote user.
1378 * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
Rekha Kumar07366812015-03-24 16:42:31 -07001379 */
1380 public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE = 5;
1381
Tyler Gunn75958422015-04-15 14:23:42 -07001382 private static final int MSG_ADD_VIDEO_CALLBACK = 1;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001383 private static final int MSG_SET_CAMERA = 2;
1384 private static final int MSG_SET_PREVIEW_SURFACE = 3;
1385 private static final int MSG_SET_DISPLAY_SURFACE = 4;
1386 private static final int MSG_SET_DEVICE_ORIENTATION = 5;
1387 private static final int MSG_SET_ZOOM = 6;
1388 private static final int MSG_SEND_SESSION_MODIFY_REQUEST = 7;
1389 private static final int MSG_SEND_SESSION_MODIFY_RESPONSE = 8;
1390 private static final int MSG_REQUEST_CAMERA_CAPABILITIES = 9;
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001391 private static final int MSG_REQUEST_CONNECTION_DATA_USAGE = 10;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001392 private static final int MSG_SET_PAUSE_IMAGE = 11;
Tyler Gunn75958422015-04-15 14:23:42 -07001393 private static final int MSG_REMOVE_VIDEO_CALLBACK = 12;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001394
Tyler Gunn6f657ee2016-09-02 09:55:25 -07001395 private static final String SESSION_EVENT_RX_PAUSE_STR = "RX_PAUSE";
1396 private static final String SESSION_EVENT_RX_RESUME_STR = "RX_RESUME";
1397 private static final String SESSION_EVENT_TX_START_STR = "TX_START";
1398 private static final String SESSION_EVENT_TX_STOP_STR = "TX_STOP";
1399 private static final String SESSION_EVENT_CAMERA_FAILURE_STR = "CAMERA_FAIL";
1400 private static final String SESSION_EVENT_CAMERA_READY_STR = "CAMERA_READY";
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001401 private static final String SESSION_EVENT_CAMERA_PERMISSION_ERROR_STR =
1402 "CAMERA_PERMISSION_ERROR";
Tyler Gunn6f657ee2016-09-02 09:55:25 -07001403 private static final String SESSION_EVENT_UNKNOWN_STR = "UNKNOWN";
1404
Tyler Gunn4e9bbaf2015-05-22 15:43:28 -07001405 private VideoProvider.VideoProviderHandler mMessageHandler;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001406 private final VideoProvider.VideoProviderBinder mBinder;
Tyler Gunn75958422015-04-15 14:23:42 -07001407
1408 /**
1409 * Stores a list of the video callbacks, keyed by IBinder.
Tyler Gunn84f381b2015-06-12 09:26:45 -07001410 *
1411 * ConcurrentHashMap constructor params: 8 is initial table size, 0.9f is
1412 * load factor before resizing, 1 means we only expect a single thread to
1413 * access the map so make only a single shard
Tyler Gunn75958422015-04-15 14:23:42 -07001414 */
Tyler Gunn84f381b2015-06-12 09:26:45 -07001415 private ConcurrentHashMap<IBinder, IVideoCallback> mVideoCallbacks =
1416 new ConcurrentHashMap<IBinder, IVideoCallback>(8, 0.9f, 1);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001417
1418 /**
1419 * Default handler used to consolidate binder method calls onto a single thread.
1420 */
1421 private final class VideoProviderHandler extends Handler {
Tyler Gunn4e9bbaf2015-05-22 15:43:28 -07001422 public VideoProviderHandler() {
1423 super();
1424 }
1425
1426 public VideoProviderHandler(Looper looper) {
1427 super(looper);
1428 }
1429
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001430 @Override
1431 public void handleMessage(Message msg) {
1432 switch (msg.what) {
Tyler Gunn75958422015-04-15 14:23:42 -07001433 case MSG_ADD_VIDEO_CALLBACK: {
1434 IBinder binder = (IBinder) msg.obj;
1435 IVideoCallback callback = IVideoCallback.Stub
1436 .asInterface((IBinder) msg.obj);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001437 if (callback == null) {
1438 Log.w(this, "addVideoProvider - skipped; callback is null.");
1439 break;
1440 }
1441
Tyler Gunn75958422015-04-15 14:23:42 -07001442 if (mVideoCallbacks.containsKey(binder)) {
1443 Log.i(this, "addVideoProvider - skipped; already present.");
1444 break;
1445 }
1446 mVideoCallbacks.put(binder, callback);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001447 break;
Tyler Gunn75958422015-04-15 14:23:42 -07001448 }
1449 case MSG_REMOVE_VIDEO_CALLBACK: {
1450 IBinder binder = (IBinder) msg.obj;
1451 IVideoCallback callback = IVideoCallback.Stub
1452 .asInterface((IBinder) msg.obj);
1453 if (!mVideoCallbacks.containsKey(binder)) {
1454 Log.i(this, "removeVideoProvider - skipped; not present.");
1455 break;
1456 }
1457 mVideoCallbacks.remove(binder);
1458 break;
1459 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001460 case MSG_SET_CAMERA:
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001461 {
1462 SomeArgs args = (SomeArgs) msg.obj;
1463 try {
1464 onSetCamera((String) args.arg1);
1465 onSetCamera((String) args.arg1, (String) args.arg2, args.argi1,
Tyler Gunn159f35c2017-03-02 09:28:37 -08001466 args.argi2, args.argi3);
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001467 } finally {
1468 args.recycle();
1469 }
1470 }
1471 break;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001472 case MSG_SET_PREVIEW_SURFACE:
1473 onSetPreviewSurface((Surface) msg.obj);
1474 break;
1475 case MSG_SET_DISPLAY_SURFACE:
1476 onSetDisplaySurface((Surface) msg.obj);
1477 break;
1478 case MSG_SET_DEVICE_ORIENTATION:
1479 onSetDeviceOrientation(msg.arg1);
1480 break;
1481 case MSG_SET_ZOOM:
1482 onSetZoom((Float) msg.obj);
1483 break;
Tyler Gunn45382162015-05-06 08:52:27 -07001484 case MSG_SEND_SESSION_MODIFY_REQUEST: {
1485 SomeArgs args = (SomeArgs) msg.obj;
1486 try {
1487 onSendSessionModifyRequest((VideoProfile) args.arg1,
1488 (VideoProfile) args.arg2);
1489 } finally {
1490 args.recycle();
1491 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001492 break;
Tyler Gunn45382162015-05-06 08:52:27 -07001493 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001494 case MSG_SEND_SESSION_MODIFY_RESPONSE:
1495 onSendSessionModifyResponse((VideoProfile) msg.obj);
1496 break;
1497 case MSG_REQUEST_CAMERA_CAPABILITIES:
1498 onRequestCameraCapabilities();
1499 break;
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001500 case MSG_REQUEST_CONNECTION_DATA_USAGE:
1501 onRequestConnectionDataUsage();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001502 break;
1503 case MSG_SET_PAUSE_IMAGE:
Yorke Lee32f24732015-05-12 16:18:03 -07001504 onSetPauseImage((Uri) msg.obj);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001505 break;
1506 default:
1507 break;
1508 }
1509 }
1510 }
1511
1512 /**
1513 * IVideoProvider stub implementation.
1514 */
1515 private final class VideoProviderBinder extends IVideoProvider.Stub {
Tyler Gunn75958422015-04-15 14:23:42 -07001516 public void addVideoCallback(IBinder videoCallbackBinder) {
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001517 mMessageHandler.obtainMessage(
Tyler Gunn75958422015-04-15 14:23:42 -07001518 MSG_ADD_VIDEO_CALLBACK, videoCallbackBinder).sendToTarget();
1519 }
1520
1521 public void removeVideoCallback(IBinder videoCallbackBinder) {
1522 mMessageHandler.obtainMessage(
1523 MSG_REMOVE_VIDEO_CALLBACK, videoCallbackBinder).sendToTarget();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001524 }
1525
Tyler Gunn159f35c2017-03-02 09:28:37 -08001526 public void setCamera(String cameraId, String callingPackageName,
1527 int targetSdkVersion) {
1528
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001529 SomeArgs args = SomeArgs.obtain();
1530 args.arg1 = cameraId;
1531 // Propagate the calling package; originally determined in
1532 // android.telecom.InCallService.VideoCall#setCamera(String) from the calling
1533 // process.
1534 args.arg2 = callingPackageName;
1535 // Pass along the uid and pid of the calling app; this gets lost when we put the
1536 // message onto the handler. These are required for Telecom to perform a permission
1537 // check to see if the calling app is able to use the camera.
1538 args.argi1 = Binder.getCallingUid();
1539 args.argi2 = Binder.getCallingPid();
Tyler Gunn159f35c2017-03-02 09:28:37 -08001540 // Pass along the target SDK version of the calling InCallService. This is used to
1541 // maintain backwards compatibility of the API for older callers.
1542 args.argi3 = targetSdkVersion;
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001543 mMessageHandler.obtainMessage(MSG_SET_CAMERA, args).sendToTarget();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001544 }
1545
1546 public void setPreviewSurface(Surface surface) {
1547 mMessageHandler.obtainMessage(MSG_SET_PREVIEW_SURFACE, surface).sendToTarget();
1548 }
1549
1550 public void setDisplaySurface(Surface surface) {
1551 mMessageHandler.obtainMessage(MSG_SET_DISPLAY_SURFACE, surface).sendToTarget();
1552 }
1553
1554 public void setDeviceOrientation(int rotation) {
Rekha Kumar07366812015-03-24 16:42:31 -07001555 mMessageHandler.obtainMessage(
1556 MSG_SET_DEVICE_ORIENTATION, rotation, 0).sendToTarget();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001557 }
1558
1559 public void setZoom(float value) {
1560 mMessageHandler.obtainMessage(MSG_SET_ZOOM, value).sendToTarget();
1561 }
1562
Tyler Gunn45382162015-05-06 08:52:27 -07001563 public void sendSessionModifyRequest(VideoProfile fromProfile, VideoProfile toProfile) {
1564 SomeArgs args = SomeArgs.obtain();
1565 args.arg1 = fromProfile;
1566 args.arg2 = toProfile;
1567 mMessageHandler.obtainMessage(MSG_SEND_SESSION_MODIFY_REQUEST, args).sendToTarget();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001568 }
1569
1570 public void sendSessionModifyResponse(VideoProfile responseProfile) {
1571 mMessageHandler.obtainMessage(
1572 MSG_SEND_SESSION_MODIFY_RESPONSE, responseProfile).sendToTarget();
1573 }
1574
1575 public void requestCameraCapabilities() {
1576 mMessageHandler.obtainMessage(MSG_REQUEST_CAMERA_CAPABILITIES).sendToTarget();
1577 }
1578
1579 public void requestCallDataUsage() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001580 mMessageHandler.obtainMessage(MSG_REQUEST_CONNECTION_DATA_USAGE).sendToTarget();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001581 }
1582
Yorke Lee32f24732015-05-12 16:18:03 -07001583 public void setPauseImage(Uri uri) {
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001584 mMessageHandler.obtainMessage(MSG_SET_PAUSE_IMAGE, uri).sendToTarget();
1585 }
1586 }
1587
1588 public VideoProvider() {
1589 mBinder = new VideoProvider.VideoProviderBinder();
Tyler Gunn84f381b2015-06-12 09:26:45 -07001590 mMessageHandler = new VideoProvider.VideoProviderHandler(Looper.getMainLooper());
Tyler Gunn4e9bbaf2015-05-22 15:43:28 -07001591 }
1592
1593 /**
1594 * Creates an instance of the {@link VideoProvider}, specifying the looper to use.
1595 *
1596 * @param looper The looper.
1597 * @hide
1598 */
Mathew Inwood42346d12018-08-01 11:33:05 +01001599 @UnsupportedAppUsage
Tyler Gunn4e9bbaf2015-05-22 15:43:28 -07001600 public VideoProvider(Looper looper) {
1601 mBinder = new VideoProvider.VideoProviderBinder();
1602 mMessageHandler = new VideoProvider.VideoProviderHandler(looper);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001603 }
1604
1605 /**
1606 * Returns binder object which can be used across IPC methods.
1607 * @hide
1608 */
1609 public final IVideoProvider getInterface() {
1610 return mBinder;
1611 }
1612
1613 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001614 * Sets the camera to be used for the outgoing video.
1615 * <p>
1616 * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
1617 * camera via
1618 * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
1619 * <p>
1620 * Sent from the {@link InCallService} via
1621 * {@link InCallService.VideoCall#setCamera(String)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001622 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001623 * @param cameraId The id of the camera (use ids as reported by
1624 * {@link CameraManager#getCameraIdList()}).
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001625 */
1626 public abstract void onSetCamera(String cameraId);
1627
1628 /**
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001629 * Sets the camera to be used for the outgoing video.
1630 * <p>
1631 * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
1632 * camera via
1633 * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
1634 * <p>
1635 * This prototype is used internally to ensure that the calling package name, UID and PID
1636 * are sent to Telecom so that can perform a camera permission check on the caller.
1637 * <p>
1638 * Sent from the {@link InCallService} via
1639 * {@link InCallService.VideoCall#setCamera(String)}.
1640 *
1641 * @param cameraId The id of the camera (use ids as reported by
1642 * {@link CameraManager#getCameraIdList()}).
1643 * @param callingPackageName The AppOpps package name of the caller.
1644 * @param callingUid The UID of the caller.
1645 * @param callingPid The PID of the caller.
Tyler Gunn159f35c2017-03-02 09:28:37 -08001646 * @param targetSdkVersion The target SDK version of the caller.
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001647 * @hide
1648 */
1649 public void onSetCamera(String cameraId, String callingPackageName, int callingUid,
Tyler Gunn159f35c2017-03-02 09:28:37 -08001650 int callingPid, int targetSdkVersion) {}
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001651
1652 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001653 * Sets the surface to be used for displaying a preview of what the user's camera is
1654 * currently capturing. When video transmission is enabled, this is the video signal which
1655 * is sent to the remote device.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001656 * <p>
1657 * Sent from the {@link InCallService} via
1658 * {@link InCallService.VideoCall#setPreviewSurface(Surface)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001659 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001660 * @param surface The {@link Surface}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001661 */
1662 public abstract void onSetPreviewSurface(Surface surface);
1663
1664 /**
1665 * Sets the surface to be used for displaying the video received from the remote device.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001666 * <p>
1667 * Sent from the {@link InCallService} via
1668 * {@link InCallService.VideoCall#setDisplaySurface(Surface)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001669 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001670 * @param surface The {@link Surface}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001671 */
1672 public abstract void onSetDisplaySurface(Surface surface);
1673
1674 /**
1675 * Sets the device orientation, in degrees. Assumes that a standard portrait orientation of
1676 * the device is 0 degrees.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001677 * <p>
1678 * Sent from the {@link InCallService} via
1679 * {@link InCallService.VideoCall#setDeviceOrientation(int)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001680 *
1681 * @param rotation The device orientation, in degrees.
1682 */
1683 public abstract void onSetDeviceOrientation(int rotation);
1684
1685 /**
1686 * Sets camera zoom ratio.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001687 * <p>
1688 * Sent from the {@link InCallService} via {@link InCallService.VideoCall#setZoom(float)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001689 *
1690 * @param value The camera zoom ratio.
1691 */
1692 public abstract void onSetZoom(float value);
1693
1694 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001695 * Issues a request to modify the properties of the current video session.
1696 * <p>
1697 * Example scenarios include: requesting an audio-only call to be upgraded to a
1698 * bi-directional video call, turning on or off the user's camera, sending a pause signal
1699 * when the {@link InCallService} is no longer the foreground application.
1700 * <p>
1701 * If the {@link VideoProvider} determines a request to be invalid, it should call
1702 * {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)} to report the
1703 * invalid request back to the {@link InCallService}.
1704 * <p>
1705 * Where a request requires confirmation from the user of the peer device, the
1706 * {@link VideoProvider} must communicate the request to the peer device and handle the
1707 * user's response. {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)}
1708 * is used to inform the {@link InCallService} of the result of the request.
1709 * <p>
1710 * Sent from the {@link InCallService} via
1711 * {@link InCallService.VideoCall#sendSessionModifyRequest(VideoProfile)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001712 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001713 * @param fromProfile The video profile prior to the request.
1714 * @param toProfile The video profile with the requested changes made.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001715 */
Tyler Gunn45382162015-05-06 08:52:27 -07001716 public abstract void onSendSessionModifyRequest(VideoProfile fromProfile,
1717 VideoProfile toProfile);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001718
Tyler Gunnb702ef82015-05-29 11:51:53 -07001719 /**
1720 * Provides a response to a request to change the current video session properties.
1721 * <p>
1722 * For example, if the peer requests and upgrade from an audio-only call to a bi-directional
1723 * video call, could decline the request and keep the call as audio-only.
1724 * In such a scenario, the {@code responseProfile} would have a video state of
1725 * {@link VideoProfile#STATE_AUDIO_ONLY}. If the user had decided to accept the request,
1726 * the video state would be {@link VideoProfile#STATE_BIDIRECTIONAL}.
1727 * <p>
1728 * Sent from the {@link InCallService} via
1729 * {@link InCallService.VideoCall#sendSessionModifyResponse(VideoProfile)} in response to
1730 * a {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)}
1731 * callback.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001732 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001733 * @param responseProfile The response video profile.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001734 */
1735 public abstract void onSendSessionModifyResponse(VideoProfile responseProfile);
1736
1737 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001738 * Issues a request to the {@link VideoProvider} to retrieve the camera capabilities.
1739 * <p>
1740 * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
1741 * camera via
1742 * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
1743 * <p>
1744 * Sent from the {@link InCallService} via
1745 * {@link InCallService.VideoCall#requestCameraCapabilities()}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001746 */
1747 public abstract void onRequestCameraCapabilities();
1748
1749 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001750 * Issues a request to the {@link VideoProvider} to retrieve the current data usage for the
1751 * video component of the current {@link Connection}.
1752 * <p>
1753 * The {@link VideoProvider} should respond by communicating current data usage, in bytes,
1754 * via {@link VideoProvider#setCallDataUsage(long)}.
1755 * <p>
1756 * Sent from the {@link InCallService} via
1757 * {@link InCallService.VideoCall#requestCallDataUsage()}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001758 */
Ihab Awad5c9c86e2014-11-12 13:41:16 -08001759 public abstract void onRequestConnectionDataUsage();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001760
1761 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001762 * Provides the {@link VideoProvider} with the {@link Uri} of an image to be displayed to
1763 * the peer device when the video signal is paused.
1764 * <p>
1765 * Sent from the {@link InCallService} via
1766 * {@link InCallService.VideoCall#setPauseImage(Uri)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001767 *
1768 * @param uri URI of image to display.
1769 */
Yorke Lee32f24732015-05-12 16:18:03 -07001770 public abstract void onSetPauseImage(Uri uri);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001771
1772 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001773 * Used to inform listening {@link InCallService} implementations when the
1774 * {@link VideoProvider} receives a session modification request.
1775 * <p>
1776 * Received by the {@link InCallService} via
1777 * {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)},
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001778 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001779 * @param videoProfile The requested video profile.
1780 * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001781 */
1782 public void receiveSessionModifyRequest(VideoProfile videoProfile) {
Tyler Gunn75958422015-04-15 14:23:42 -07001783 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001784 for (IVideoCallback callback : mVideoCallbacks.values()) {
1785 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001786 callback.receiveSessionModifyRequest(videoProfile);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001787 } catch (RemoteException ignored) {
1788 Log.w(this, "receiveSessionModifyRequest callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001789 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001790 }
1791 }
1792 }
1793
1794 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001795 * Used to inform listening {@link InCallService} implementations when the
1796 * {@link VideoProvider} receives a response to a session modification request.
1797 * <p>
1798 * Received by the {@link InCallService} via
1799 * {@link InCallService.VideoCall.Callback#onSessionModifyResponseReceived(int,
1800 * VideoProfile, VideoProfile)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001801 *
1802 * @param status Status of the session modify request. Valid values are
1803 * {@link VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
1804 * {@link VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
Tyler Gunnb702ef82015-05-29 11:51:53 -07001805 * {@link VideoProvider#SESSION_MODIFY_REQUEST_INVALID},
1806 * {@link VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT},
1807 * {@link VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE}
1808 * @param requestedProfile The original request which was sent to the peer device.
1809 * @param responseProfile The actual profile changes agreed to by the peer device.
1810 * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001811 */
1812 public void receiveSessionModifyResponse(int status,
1813 VideoProfile requestedProfile, VideoProfile responseProfile) {
Tyler Gunn75958422015-04-15 14:23:42 -07001814 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001815 for (IVideoCallback callback : mVideoCallbacks.values()) {
1816 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001817 callback.receiveSessionModifyResponse(status, requestedProfile,
1818 responseProfile);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001819 } catch (RemoteException ignored) {
1820 Log.w(this, "receiveSessionModifyResponse callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001821 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001822 }
1823 }
1824 }
1825
1826 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001827 * Used to inform listening {@link InCallService} implementations when the
1828 * {@link VideoProvider} reports a call session event.
1829 * <p>
1830 * Received by the {@link InCallService} via
1831 * {@link InCallService.VideoCall.Callback#onCallSessionEvent(int)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001832 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001833 * @param event The event. Valid values are: {@link VideoProvider#SESSION_EVENT_RX_PAUSE},
1834 * {@link VideoProvider#SESSION_EVENT_RX_RESUME},
1835 * {@link VideoProvider#SESSION_EVENT_TX_START},
1836 * {@link VideoProvider#SESSION_EVENT_TX_STOP},
1837 * {@link VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001838 * {@link VideoProvider#SESSION_EVENT_CAMERA_READY},
1839 * {@link VideoProvider#SESSION_EVENT_CAMERA_FAILURE}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001840 */
1841 public void handleCallSessionEvent(int event) {
Tyler Gunn75958422015-04-15 14:23:42 -07001842 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001843 for (IVideoCallback callback : mVideoCallbacks.values()) {
1844 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001845 callback.handleCallSessionEvent(event);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001846 } catch (RemoteException ignored) {
1847 Log.w(this, "handleCallSessionEvent callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001848 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001849 }
1850 }
1851 }
1852
1853 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001854 * Used to inform listening {@link InCallService} implementations when the dimensions of the
1855 * peer's video have changed.
1856 * <p>
1857 * This could occur if, for example, the peer rotates their device, changing the aspect
1858 * ratio of the video, or if the user switches between the back and front cameras.
1859 * <p>
1860 * Received by the {@link InCallService} via
1861 * {@link InCallService.VideoCall.Callback#onPeerDimensionsChanged(int, int)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001862 *
1863 * @param width The updated peer video width.
1864 * @param height The updated peer video height.
1865 */
1866 public void changePeerDimensions(int width, int height) {
Tyler Gunn75958422015-04-15 14:23:42 -07001867 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001868 for (IVideoCallback callback : mVideoCallbacks.values()) {
1869 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001870 callback.changePeerDimensions(width, height);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001871 } catch (RemoteException ignored) {
1872 Log.w(this, "changePeerDimensions callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001873 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001874 }
1875 }
1876 }
1877
1878 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001879 * Used to inform listening {@link InCallService} implementations when the data usage of the
1880 * video associated with the current {@link Connection} has changed.
1881 * <p>
1882 * This could be in response to a preview request via
1883 * {@link #onRequestConnectionDataUsage()}, or as a periodic update by the
Tyler Gunn295f5d72015-06-04 11:08:54 -07001884 * {@link VideoProvider}. Where periodic updates of data usage are provided, they should be
1885 * provided at most for every 1 MB of data transferred and no more than once every 10 sec.
Tyler Gunnb702ef82015-05-29 11:51:53 -07001886 * <p>
1887 * Received by the {@link InCallService} via
1888 * {@link InCallService.VideoCall.Callback#onCallDataUsageChanged(long)}.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001889 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001890 * @param dataUsage The updated data usage (in bytes). Reported as the cumulative bytes
1891 * used since the start of the call.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001892 */
Yorke Lee32f24732015-05-12 16:18:03 -07001893 public void setCallDataUsage(long dataUsage) {
Tyler Gunn75958422015-04-15 14:23:42 -07001894 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001895 for (IVideoCallback callback : mVideoCallbacks.values()) {
1896 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001897 callback.changeCallDataUsage(dataUsage);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001898 } catch (RemoteException ignored) {
1899 Log.w(this, "setCallDataUsage callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001900 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001901 }
1902 }
1903 }
1904
1905 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001906 * @see #setCallDataUsage(long)
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001907 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001908 * @param dataUsage The updated data usage (in byes).
Yorke Lee32f24732015-05-12 16:18:03 -07001909 * @deprecated - Use {@link #setCallDataUsage(long)} instead.
1910 * @hide
1911 */
1912 public void changeCallDataUsage(long dataUsage) {
1913 setCallDataUsage(dataUsage);
1914 }
1915
1916 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001917 * Used to inform listening {@link InCallService} implementations when the capabilities of
1918 * the current camera have changed.
1919 * <p>
1920 * The {@link VideoProvider} should call this in response to
1921 * {@link VideoProvider#onRequestCameraCapabilities()}, or when the current camera is
1922 * changed via {@link VideoProvider#onSetCamera(String)}.
1923 * <p>
1924 * Received by the {@link InCallService} via
1925 * {@link InCallService.VideoCall.Callback#onCameraCapabilitiesChanged(
1926 * VideoProfile.CameraCapabilities)}.
Yorke Lee32f24732015-05-12 16:18:03 -07001927 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001928 * @param cameraCapabilities The new camera capabilities.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001929 */
Yorke Lee400470f2015-05-12 13:31:25 -07001930 public void changeCameraCapabilities(VideoProfile.CameraCapabilities cameraCapabilities) {
Tyler Gunn75958422015-04-15 14:23:42 -07001931 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001932 for (IVideoCallback callback : mVideoCallbacks.values()) {
1933 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001934 callback.changeCameraCapabilities(cameraCapabilities);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001935 } catch (RemoteException ignored) {
1936 Log.w(this, "changeCameraCapabilities callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001937 }
Ihab Awadb19a0bc2014-08-07 19:46:01 -07001938 }
1939 }
1940 }
Rekha Kumar07366812015-03-24 16:42:31 -07001941
1942 /**
Tyler Gunnb702ef82015-05-29 11:51:53 -07001943 * Used to inform listening {@link InCallService} implementations when the video quality
1944 * of the call has changed.
1945 * <p>
1946 * Received by the {@link InCallService} via
1947 * {@link InCallService.VideoCall.Callback#onVideoQualityChanged(int)}.
Rekha Kumar07366812015-03-24 16:42:31 -07001948 *
Tyler Gunnb702ef82015-05-29 11:51:53 -07001949 * @param videoQuality The updated video quality. Valid values:
1950 * {@link VideoProfile#QUALITY_HIGH},
1951 * {@link VideoProfile#QUALITY_MEDIUM},
1952 * {@link VideoProfile#QUALITY_LOW},
1953 * {@link VideoProfile#QUALITY_DEFAULT}.
Rekha Kumar07366812015-03-24 16:42:31 -07001954 */
1955 public void changeVideoQuality(int videoQuality) {
Tyler Gunn75958422015-04-15 14:23:42 -07001956 if (mVideoCallbacks != null) {
Tyler Gunn84f381b2015-06-12 09:26:45 -07001957 for (IVideoCallback callback : mVideoCallbacks.values()) {
1958 try {
Tyler Gunn75958422015-04-15 14:23:42 -07001959 callback.changeVideoQuality(videoQuality);
Tyler Gunn84f381b2015-06-12 09:26:45 -07001960 } catch (RemoteException ignored) {
1961 Log.w(this, "changeVideoQuality callback failed", ignored);
Tyler Gunn75958422015-04-15 14:23:42 -07001962 }
Rekha Kumar07366812015-03-24 16:42:31 -07001963 }
1964 }
1965 }
Tyler Gunn6f657ee2016-09-02 09:55:25 -07001966
1967 /**
1968 * Returns a string representation of a call session event.
1969 *
1970 * @param event A call session event passed to {@link #handleCallSessionEvent(int)}.
1971 * @return String representation of the call session event.
1972 * @hide
1973 */
1974 public static String sessionEventToString(int event) {
1975 switch (event) {
1976 case SESSION_EVENT_CAMERA_FAILURE:
1977 return SESSION_EVENT_CAMERA_FAILURE_STR;
1978 case SESSION_EVENT_CAMERA_READY:
1979 return SESSION_EVENT_CAMERA_READY_STR;
1980 case SESSION_EVENT_RX_PAUSE:
1981 return SESSION_EVENT_RX_PAUSE_STR;
1982 case SESSION_EVENT_RX_RESUME:
1983 return SESSION_EVENT_RX_RESUME_STR;
1984 case SESSION_EVENT_TX_START:
1985 return SESSION_EVENT_TX_START_STR;
1986 case SESSION_EVENT_TX_STOP:
1987 return SESSION_EVENT_TX_STOP_STR;
Tyler Gunnbf9c6fd2016-11-09 10:19:23 -08001988 case SESSION_EVENT_CAMERA_PERMISSION_ERROR:
1989 return SESSION_EVENT_CAMERA_PERMISSION_ERROR_STR;
Tyler Gunn6f657ee2016-09-02 09:55:25 -07001990 default:
1991 return SESSION_EVENT_UNKNOWN_STR + " " + event;
1992 }
1993 }
Ihab Awad542e0ea2014-05-16 10:22:16 -07001994 }
1995
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07001996 private final Listener mConnectionDeathListener = new Listener() {
1997 @Override
1998 public void onDestroyed(Connection c) {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08001999 if (mConferenceables.remove(c)) {
2000 fireOnConferenceableConnectionsChanged();
2001 }
2002 }
2003 };
2004
2005 private final Conference.Listener mConferenceDeathListener = new Conference.Listener() {
2006 @Override
2007 public void onDestroyed(Conference c) {
2008 if (mConferenceables.remove(c)) {
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002009 fireOnConferenceableConnectionsChanged();
2010 }
2011 }
2012 };
2013
Jay Shrauner229e3822014-08-15 09:23:07 -07002014 /**
2015 * ConcurrentHashMap constructor params: 8 is initial table size, 0.9f is
2016 * load factor before resizing, 1 means we only expect a single thread to
2017 * access the map so make only a single shard
2018 */
2019 private final Set<Listener> mListeners = Collections.newSetFromMap(
2020 new ConcurrentHashMap<Listener, Boolean>(8, 0.9f, 1));
Tyler Gunndf2cbc82015-04-20 09:13:01 -07002021 private final List<Conferenceable> mConferenceables = new ArrayList<>();
2022 private final List<Conferenceable> mUnmodifiableConferenceables =
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002023 Collections.unmodifiableList(mConferenceables);
Santos Cordonb6939982014-06-04 20:20:58 -07002024
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002025 // The internal telecom call ID associated with this connection.
2026 private String mTelecomCallId;
Pengquan Meng70c9885332017-10-02 18:09:03 -07002027 // The PhoneAccountHandle associated with this connection.
2028 private PhoneAccountHandle mPhoneAccountHandle;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002029 private int mState = STATE_NEW;
Yorke Lee4af59352015-05-13 14:14:54 -07002030 private CallAudioState mCallAudioState;
Andrew Lee100e2932014-09-08 15:34:24 -07002031 private Uri mAddress;
2032 private int mAddressPresentation;
Sailesh Nepal61203862014-07-11 14:50:13 -07002033 private String mCallerDisplayName;
2034 private int mCallerDisplayNamePresentation;
Andrew Lee100e2932014-09-08 15:34:24 -07002035 private boolean mRingbackRequested = false;
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002036 private int mConnectionCapabilities;
Tyler Gunn720c6642016-03-22 09:02:47 -07002037 private int mConnectionProperties;
Christine Hallstrom2830ce92016-11-30 16:06:42 -08002038 private int mSupportedAudioRoutes = CallAudioState.ROUTE_ALL;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002039 private VideoProvider mVideoProvider;
Sailesh Nepal33aaae42014-07-07 22:49:44 -07002040 private boolean mAudioModeIsVoip;
Roshan Piuse927ec02015-07-15 15:47:21 -07002041 private long mConnectTimeMillis = Conference.CONNECT_TIME_NOT_SPECIFIED;
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002042 private long mConnectElapsedTimeMillis = Conference.CONNECT_TIME_NOT_SPECIFIED;
Sailesh Nepale7ef59a2014-07-08 21:48:22 -07002043 private StatusHints mStatusHints;
Tyler Gunnaa07df82014-07-17 07:50:22 -07002044 private int mVideoState;
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002045 private DisconnectCause mDisconnectCause;
Santos Cordon823fd3c2014-08-07 18:35:18 -07002046 private Conference mConference;
2047 private ConnectionService mConnectionService;
Santos Cordon6b7f9552015-05-27 17:21:45 -07002048 private Bundle mExtras;
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002049 private final Object mExtrasLock = new Object();
Tyler Gunn6986a632019-06-25 13:45:32 -07002050 /**
2051 * The direction of the connection; used where an existing connection is created and we need to
2052 * communicate to Telecom whether its incoming or outgoing.
2053 */
2054 private @Call.Details.CallDirection int mCallDirection = Call.Details.DIRECTION_UNKNOWN;
Ihab Awad542e0ea2014-05-16 10:22:16 -07002055
2056 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07002057 * Tracks the key set for the extras bundle provided on the last invocation of
2058 * {@link #setExtras(Bundle)}. Used so that on subsequent invocations we can remove any extras
2059 * keys which were set previously but are no longer present in the replacement Bundle.
2060 */
2061 private Set<String> mPreviousExtraKeys;
2062
2063 /**
Tyler Gunnd57d76c2019-09-24 14:53:23 -07002064 * The verification status for an incoming call's phone number.
2065 */
2066 private @VerificationStatus int mCallerNumberVerificationStatus;
2067
2068
2069 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07002070 * Create a new Connection.
2071 */
Santos Cordonf2951102014-07-20 19:06:29 -07002072 public Connection() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07002073
2074 /**
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002075 * Returns the Telecom internal call ID associated with this connection. Should only be used
2076 * for debugging and tracing purposes.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002077 * <p>
2078 * Note: Access to the Telecom internal call ID is used for logging purposes only; this API is
2079 * provided to facilitate debugging of the Telephony stack only.
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002080 *
Tyler Gunnc63f9082019-10-15 13:19:26 -07002081 * @return The Telecom call ID, or {@code null} if it was not set.
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002082 * @hide
2083 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002084 @SystemApi
2085 public final @Nullable String getTelecomCallId() {
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002086 return mTelecomCallId;
2087 }
2088
2089 /**
Andrew Lee100e2932014-09-08 15:34:24 -07002090 * @return The address (e.g., phone number) to which this Connection is currently communicating.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002091 */
Andrew Lee100e2932014-09-08 15:34:24 -07002092 public final Uri getAddress() {
2093 return mAddress;
Ihab Awad542e0ea2014-05-16 10:22:16 -07002094 }
2095
2096 /**
Andrew Lee100e2932014-09-08 15:34:24 -07002097 * @return The presentation requirements for the address.
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002098 * See {@link TelecomManager} for valid values.
Sailesh Nepal61203862014-07-11 14:50:13 -07002099 */
Andrew Lee100e2932014-09-08 15:34:24 -07002100 public final int getAddressPresentation() {
2101 return mAddressPresentation;
Sailesh Nepal61203862014-07-11 14:50:13 -07002102 }
2103
2104 /**
2105 * @return The caller display name (CNAP).
2106 */
2107 public final String getCallerDisplayName() {
2108 return mCallerDisplayName;
2109 }
2110
2111 /**
Nancy Chen9d568c02014-09-08 14:17:59 -07002112 * @return The presentation requirements for the handle.
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002113 * See {@link TelecomManager} for valid values.
Sailesh Nepal61203862014-07-11 14:50:13 -07002114 */
2115 public final int getCallerDisplayNamePresentation() {
2116 return mCallerDisplayNamePresentation;
2117 }
2118
2119 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07002120 * @return The state of this Connection.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002121 */
2122 public final int getState() {
2123 return mState;
2124 }
2125
2126 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002127 * Returns the video state of the connection.
Yorke Lee32f24732015-05-12 16:18:03 -07002128 * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
2129 * {@link VideoProfile#STATE_BIDIRECTIONAL},
2130 * {@link VideoProfile#STATE_TX_ENABLED},
2131 * {@link VideoProfile#STATE_RX_ENABLED}.
Tyler Gunnaa07df82014-07-17 07:50:22 -07002132 *
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002133 * @return The video state of the connection.
Tyler Gunnaa07df82014-07-17 07:50:22 -07002134 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002135 public final @VideoProfile.VideoState int getVideoState() {
Tyler Gunnaa07df82014-07-17 07:50:22 -07002136 return mVideoState;
2137 }
2138
2139 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002140 * @return The audio state of the connection, describing how its audio is currently
Ihab Awad542e0ea2014-05-16 10:22:16 -07002141 * being routed by the system. This is {@code null} if this Connection
2142 * does not directly know about its audio state.
Yorke Lee4af59352015-05-13 14:14:54 -07002143 * @deprecated Use {@link #getCallAudioState()} instead.
2144 * @hide
Ihab Awad542e0ea2014-05-16 10:22:16 -07002145 */
Yorke Lee4af59352015-05-13 14:14:54 -07002146 @SystemApi
2147 @Deprecated
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002148 public final AudioState getAudioState() {
Sailesh Nepal000d38a2015-06-21 10:25:13 -07002149 if (mCallAudioState == null) {
2150 return null;
2151 }
Yorke Lee4af59352015-05-13 14:14:54 -07002152 return new AudioState(mCallAudioState);
2153 }
2154
2155 /**
2156 * @return The audio state of the connection, describing how its audio is currently
2157 * being routed by the system. This is {@code null} if this Connection
2158 * does not directly know about its audio state.
2159 */
2160 public final CallAudioState getCallAudioState() {
2161 return mCallAudioState;
Ihab Awad542e0ea2014-05-16 10:22:16 -07002162 }
2163
2164 /**
Santos Cordon823fd3c2014-08-07 18:35:18 -07002165 * @return The conference that this connection is a part of. Null if it is not part of any
2166 * conference.
2167 */
2168 public final Conference getConference() {
2169 return mConference;
2170 }
2171
2172 /**
Sailesh Nepal2a46b902014-07-04 17:21:07 -07002173 * Returns whether this connection is requesting that the system play a ringback tone
2174 * on its behalf.
2175 */
Andrew Lee100e2932014-09-08 15:34:24 -07002176 public final boolean isRingbackRequested() {
2177 return mRingbackRequested;
Sailesh Nepal2a46b902014-07-04 17:21:07 -07002178 }
2179
2180 /**
Sailesh Nepal33aaae42014-07-07 22:49:44 -07002181 * @return True if the connection's audio mode is VOIP.
2182 */
2183 public final boolean getAudioModeIsVoip() {
2184 return mAudioModeIsVoip;
2185 }
2186
2187 /**
Roshan Piuse927ec02015-07-15 15:47:21 -07002188 * Retrieves the connection start time of the {@code Connnection}, if specified. A value of
2189 * {@link Conference#CONNECT_TIME_NOT_SPECIFIED} indicates that Telecom should determine the
2190 * start time of the conference.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002191 * <p>
2192 * Note: This is an implementation detail specific to IMS conference calls over a mobile
2193 * network.
Roshan Piuse927ec02015-07-15 15:47:21 -07002194 *
Tyler Gunnc63f9082019-10-15 13:19:26 -07002195 * @return The time at which the {@code Connnection} was connected. Will be a value as retrieved
2196 * from {@link System#currentTimeMillis()}.
Roshan Piuse927ec02015-07-15 15:47:21 -07002197 *
2198 * @hide
2199 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002200 @SystemApi
Tyler Gunnc9503d62020-01-27 10:30:51 -08002201 public final @IntRange(from = 0) long getConnectTimeMillis() {
Roshan Piuse927ec02015-07-15 15:47:21 -07002202 return mConnectTimeMillis;
2203 }
2204
2205 /**
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002206 * Retrieves the connection start time of the {@link Connection}, if specified. A value of
2207 * {@link Conference#CONNECT_TIME_NOT_SPECIFIED} indicates that Telecom should determine the
Tyler Gunnc9503d62020-01-27 10:30:51 -08002208 * start time of the connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002209 * <p>
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002210 * Based on the value of {@link SystemClock#elapsedRealtime()}, which ensures that wall-clock
2211 * changes do not impact the call duration.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002212 * <p>
2213 * Used internally in Telephony when migrating conference participant data for IMS conferences.
Tyler Gunnc9503d62020-01-27 10:30:51 -08002214 * <p>
2215 * The value returned is the same one set using
2216 * {@link #setConnectionStartElapsedRealtimeMillis(long)}. This value is never updated from
2217 * the Telecom framework, so no permission enforcement occurs when retrieving the value with
2218 * this method.
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002219 *
2220 * @return The time at which the {@link Connection} was connected.
2221 *
2222 * @hide
2223 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002224 @SystemApi
Tyler Gunnc9503d62020-01-27 10:30:51 -08002225 public final @ElapsedRealtimeLong long getConnectionStartElapsedRealtimeMillis() {
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002226 return mConnectElapsedTimeMillis;
2227 }
2228
2229 /**
Sailesh Nepale7ef59a2014-07-08 21:48:22 -07002230 * @return The status hints for this connection.
2231 */
2232 public final StatusHints getStatusHints() {
2233 return mStatusHints;
2234 }
2235
2236 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07002237 * Returns the extras associated with this connection.
Tyler Gunn2cbe2b52016-05-04 15:48:10 +00002238 * <p>
2239 * Extras should be updated using {@link #putExtras(Bundle)}.
2240 * <p>
2241 * Telecom or an {@link InCallService} can also update the extras via
2242 * {@link android.telecom.Call#putExtras(Bundle)}, and
2243 * {@link Call#removeExtras(List)}.
2244 * <p>
2245 * The connection is notified of changes to the extras made by Telecom or an
2246 * {@link InCallService} by {@link #onExtrasChanged(Bundle)}.
Tyler Gunndee56a82016-03-23 16:06:34 -07002247 *
Santos Cordon6b7f9552015-05-27 17:21:45 -07002248 * @return The extras associated with this connection.
2249 */
2250 public final Bundle getExtras() {
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002251 Bundle extras = null;
2252 synchronized (mExtrasLock) {
2253 if (mExtras != null) {
2254 extras = new Bundle(mExtras);
2255 }
2256 }
2257 return extras;
Santos Cordon6b7f9552015-05-27 17:21:45 -07002258 }
2259
2260 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07002261 * Assign a listener to be notified of state changes.
2262 *
2263 * @param l A listener.
2264 * @return This Connection.
2265 *
2266 * @hide
2267 */
Tyler Gunn633e4c32019-10-24 15:40:48 -07002268 final Connection addConnectionListener(Listener l) {
Santos Cordond34e5712014-08-05 18:54:03 +00002269 mListeners.add(l);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002270 return this;
2271 }
2272
2273 /**
2274 * Remove a previously assigned listener that was being notified of state changes.
2275 *
2276 * @param l A Listener.
2277 * @return This Connection.
2278 *
2279 * @hide
2280 */
Tyler Gunn633e4c32019-10-24 15:40:48 -07002281 final Connection removeConnectionListener(Listener l) {
Jay Shrauner229e3822014-08-15 09:23:07 -07002282 if (l != null) {
2283 mListeners.remove(l);
2284 }
Ihab Awad542e0ea2014-05-16 10:22:16 -07002285 return this;
2286 }
2287
2288 /**
Sailesh Nepalcf7020b2014-08-20 10:07:19 -07002289 * @return The {@link DisconnectCause} for this connection.
Evan Charltonbf11f982014-07-20 22:06:28 -07002290 */
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002291 public final DisconnectCause getDisconnectCause() {
Sailesh Nepalcf7020b2014-08-20 10:07:19 -07002292 return mDisconnectCause;
Evan Charltonbf11f982014-07-20 22:06:28 -07002293 }
2294
2295 /**
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002296 * Sets the telecom call ID associated with this Connection. The Telecom Call ID should be used
2297 * ONLY for debugging purposes.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002298 * <p>
2299 * Note: Access to the Telecom internal call ID is used for logging purposes only; this API is
2300 * provided to facilitate debugging of the Telephony stack only. Changing the ID via this
2301 * method does NOT change any functionality in Telephony or Telecom and impacts only logging.
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002302 *
2303 * @param callId The telecom call ID.
2304 * @hide
2305 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002306 @SystemApi
2307 public void setTelecomCallId(@NonNull String callId) {
Tyler Gunnf0500bd2015-09-01 10:59:48 -07002308 mTelecomCallId = callId;
2309 }
2310
2311 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07002312 * Inform this Connection that the state of its audio output has been changed externally.
2313 *
2314 * @param state The new audio state.
Sailesh Nepal400cc482014-06-26 12:04:00 -07002315 * @hide
Ihab Awad542e0ea2014-05-16 10:22:16 -07002316 */
Yorke Lee4af59352015-05-13 14:14:54 -07002317 final void setCallAudioState(CallAudioState state) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002318 checkImmutable();
Ihab Awad60ac30b2014-05-20 22:32:12 -07002319 Log.d(this, "setAudioState %s", state);
Yorke Lee4af59352015-05-13 14:14:54 -07002320 mCallAudioState = state;
2321 onAudioStateChanged(getAudioState());
2322 onCallAudioStateChanged(state);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002323 }
2324
2325 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002326 * @param state An integer value of a {@code STATE_*} constant.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002327 * @return A string representation of the value.
2328 */
2329 public static String stateToString(int state) {
2330 switch (state) {
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002331 case STATE_INITIALIZING:
Yorke Leee911c8d2015-07-14 11:39:36 -07002332 return "INITIALIZING";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002333 case STATE_NEW:
Yorke Leee911c8d2015-07-14 11:39:36 -07002334 return "NEW";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002335 case STATE_RINGING:
Yorke Leee911c8d2015-07-14 11:39:36 -07002336 return "RINGING";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002337 case STATE_DIALING:
Yorke Leee911c8d2015-07-14 11:39:36 -07002338 return "DIALING";
Tyler Gunnc96b5e02016-07-07 22:53:57 -07002339 case STATE_PULLING_CALL:
2340 return "PULLING_CALL";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002341 case STATE_ACTIVE:
Yorke Leee911c8d2015-07-14 11:39:36 -07002342 return "ACTIVE";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002343 case STATE_HOLDING:
Yorke Leee911c8d2015-07-14 11:39:36 -07002344 return "HOLDING";
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002345 case STATE_DISCONNECTED:
Ihab Awad542e0ea2014-05-16 10:22:16 -07002346 return "DISCONNECTED";
2347 default:
Ihab Awad60ac30b2014-05-20 22:32:12 -07002348 Log.wtf(Connection.class, "Unknown state %d", state);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002349 return "UNKNOWN";
2350 }
2351 }
2352
2353 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002354 * Returns the connection's capabilities, as a bit mask of the {@code CAPABILITY_*} constants.
Ihab Awad52a28f62014-06-18 10:26:34 -07002355 */
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002356 public final int getConnectionCapabilities() {
2357 return mConnectionCapabilities;
Ihab Awad52a28f62014-06-18 10:26:34 -07002358 }
2359
2360 /**
Tyler Gunn720c6642016-03-22 09:02:47 -07002361 * Returns the connection's properties, as a bit mask of the {@code PROPERTY_*} constants.
2362 */
2363 public final int getConnectionProperties() {
2364 return mConnectionProperties;
2365 }
2366
2367 /**
Christine Hallstrom2830ce92016-11-30 16:06:42 -08002368 * Returns the connection's supported audio routes.
2369 *
2370 * @hide
2371 */
2372 public final int getSupportedAudioRoutes() {
2373 return mSupportedAudioRoutes;
2374 }
2375
2376 /**
Andrew Lee100e2932014-09-08 15:34:24 -07002377 * Sets the value of the {@link #getAddress()} property.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002378 *
Andrew Lee100e2932014-09-08 15:34:24 -07002379 * @param address The new address.
2380 * @param presentation The presentation requirements for the address.
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002381 * See {@link TelecomManager} for valid values.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002382 */
Andrew Lee100e2932014-09-08 15:34:24 -07002383 public final void setAddress(Uri address, int presentation) {
2384 Log.d(this, "setAddress %s", address);
2385 mAddress = address;
2386 mAddressPresentation = presentation;
Santos Cordond34e5712014-08-05 18:54:03 +00002387 for (Listener l : mListeners) {
Andrew Lee100e2932014-09-08 15:34:24 -07002388 l.onAddressChanged(this, address, presentation);
Santos Cordond34e5712014-08-05 18:54:03 +00002389 }
Ihab Awad542e0ea2014-05-16 10:22:16 -07002390 }
2391
2392 /**
Sailesh Nepal61203862014-07-11 14:50:13 -07002393 * Sets the caller display name (CNAP).
Sailesh Nepal2a46b902014-07-04 17:21:07 -07002394 *
Sailesh Nepal61203862014-07-11 14:50:13 -07002395 * @param callerDisplayName The new display name.
Nancy Chen9d568c02014-09-08 14:17:59 -07002396 * @param presentation The presentation requirements for the handle.
Tyler Gunnef9f6f92014-09-12 22:16:17 -07002397 * See {@link TelecomManager} for valid values.
Sailesh Nepal2a46b902014-07-04 17:21:07 -07002398 */
Sailesh Nepal61203862014-07-11 14:50:13 -07002399 public final void setCallerDisplayName(String callerDisplayName, int presentation) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002400 checkImmutable();
Sailesh Nepal61203862014-07-11 14:50:13 -07002401 Log.d(this, "setCallerDisplayName %s", callerDisplayName);
Santos Cordond34e5712014-08-05 18:54:03 +00002402 mCallerDisplayName = callerDisplayName;
2403 mCallerDisplayNamePresentation = presentation;
2404 for (Listener l : mListeners) {
2405 l.onCallerDisplayNameChanged(this, callerDisplayName, presentation);
2406 }
Sailesh Nepal2a46b902014-07-04 17:21:07 -07002407 }
2408
2409 /**
Tyler Gunnaa07df82014-07-17 07:50:22 -07002410 * Set the video state for the connection.
Yorke Lee32f24732015-05-12 16:18:03 -07002411 * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
2412 * {@link VideoProfile#STATE_BIDIRECTIONAL},
2413 * {@link VideoProfile#STATE_TX_ENABLED},
2414 * {@link VideoProfile#STATE_RX_ENABLED}.
Tyler Gunnaa07df82014-07-17 07:50:22 -07002415 *
2416 * @param videoState The new video state.
2417 */
2418 public final void setVideoState(int videoState) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002419 checkImmutable();
Tyler Gunnaa07df82014-07-17 07:50:22 -07002420 Log.d(this, "setVideoState %d", videoState);
Santos Cordond34e5712014-08-05 18:54:03 +00002421 mVideoState = videoState;
2422 for (Listener l : mListeners) {
2423 l.onVideoStateChanged(this, mVideoState);
2424 }
Tyler Gunnaa07df82014-07-17 07:50:22 -07002425 }
2426
2427 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002428 * Sets state to active (e.g., an ongoing connection where two or more parties can actively
Ihab Awad542e0ea2014-05-16 10:22:16 -07002429 * communicate).
2430 */
Sailesh Nepal400cc482014-06-26 12:04:00 -07002431 public final void setActive() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002432 checkImmutable();
Andrew Lee100e2932014-09-08 15:34:24 -07002433 setRingbackRequested(false);
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002434 setState(STATE_ACTIVE);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002435 }
2436
2437 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002438 * Sets state to ringing (e.g., an inbound ringing connection).
Ihab Awad542e0ea2014-05-16 10:22:16 -07002439 */
Sailesh Nepal400cc482014-06-26 12:04:00 -07002440 public final void setRinging() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002441 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002442 setState(STATE_RINGING);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002443 }
2444
2445 /**
Evan Charltonbf11f982014-07-20 22:06:28 -07002446 * Sets state to initializing (this Connection is not yet ready to be used).
2447 */
2448 public final void setInitializing() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002449 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002450 setState(STATE_INITIALIZING);
Evan Charltonbf11f982014-07-20 22:06:28 -07002451 }
2452
2453 /**
2454 * Sets state to initialized (the Connection has been set up and is now ready to be used).
2455 */
2456 public final void setInitialized() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002457 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002458 setState(STATE_NEW);
Evan Charltonbf11f982014-07-20 22:06:28 -07002459 }
2460
2461 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002462 * Sets state to dialing (e.g., dialing an outbound connection).
Ihab Awad542e0ea2014-05-16 10:22:16 -07002463 */
Sailesh Nepal400cc482014-06-26 12:04:00 -07002464 public final void setDialing() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002465 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002466 setState(STATE_DIALING);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002467 }
2468
2469 /**
Tyler Gunnc242ceb2016-06-29 22:35:45 -07002470 * Sets state to pulling (e.g. the connection is being pulled to the local device from another
2471 * device). Only applicable for {@link Connection}s with
2472 * {@link Connection#PROPERTY_IS_EXTERNAL_CALL} and {@link Connection#CAPABILITY_CAN_PULL_CALL}.
2473 */
2474 public final void setPulling() {
2475 checkImmutable();
2476 setState(STATE_PULLING_CALL);
2477 }
2478
2479 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07002480 * Sets state to be on hold.
2481 */
Sailesh Nepal400cc482014-06-26 12:04:00 -07002482 public final void setOnHold() {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002483 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002484 setState(STATE_HOLDING);
Ihab Awad542e0ea2014-05-16 10:22:16 -07002485 }
2486
2487 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002488 * Sets the video connection provider.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002489 * @param videoProvider The video provider.
Andrew Lee5ffbe8b82014-06-20 16:29:33 -07002490 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002491 public final void setVideoProvider(VideoProvider videoProvider) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002492 checkImmutable();
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002493 mVideoProvider = videoProvider;
Santos Cordond34e5712014-08-05 18:54:03 +00002494 for (Listener l : mListeners) {
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002495 l.onVideoProviderChanged(this, videoProvider);
Santos Cordond34e5712014-08-05 18:54:03 +00002496 }
Andrew Lee5ffbe8b82014-06-20 16:29:33 -07002497 }
2498
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002499 public final VideoProvider getVideoProvider() {
2500 return mVideoProvider;
Andrew Leea27a1932014-07-09 17:07:13 -07002501 }
2502
Andrew Lee5ffbe8b82014-06-20 16:29:33 -07002503 /**
Sailesh Nepal091768c2014-06-30 15:15:23 -07002504 * Sets state to disconnected.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002505 *
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002506 * @param disconnectCause The reason for the disconnection, as specified by
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002507 * {@link DisconnectCause}.
Ihab Awad542e0ea2014-05-16 10:22:16 -07002508 */
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002509 public final void setDisconnected(DisconnectCause disconnectCause) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002510 checkImmutable();
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002511 mDisconnectCause = disconnectCause;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002512 setState(STATE_DISCONNECTED);
mike dooleyf34519b2014-09-16 17:33:40 -07002513 Log.d(this, "Disconnected with cause %s", disconnectCause);
Santos Cordond34e5712014-08-05 18:54:03 +00002514 for (Listener l : mListeners) {
Andrew Lee7f3d41f2014-09-11 17:33:16 -07002515 l.onDisconnected(this, disconnectCause);
Santos Cordond34e5712014-08-05 18:54:03 +00002516 }
Ihab Awad542e0ea2014-05-16 10:22:16 -07002517 }
2518
2519 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002520 * Informs listeners that this {@code Connection} is in a post-dial wait state. This is done
2521 * when (a) the {@code Connection} is issuing a DTMF sequence; (b) it has encountered a "wait"
2522 * character; and (c) it wishes to inform the In-Call app that it is waiting for the end-user
2523 * to send an {@link #onPostDialContinue(boolean)} signal.
2524 *
2525 * @param remaining The DTMF character sequence remaining to be emitted once the
2526 * {@link #onPostDialContinue(boolean)} is received, including any "wait" characters
2527 * that remaining sequence may contain.
Sailesh Nepal091768c2014-06-30 15:15:23 -07002528 */
2529 public final void setPostDialWait(String remaining) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002530 checkImmutable();
Santos Cordond34e5712014-08-05 18:54:03 +00002531 for (Listener l : mListeners) {
2532 l.onPostDialWait(this, remaining);
2533 }
Sailesh Nepal091768c2014-06-30 15:15:23 -07002534 }
2535
2536 /**
Nancy Chen27d1c2d2014-12-15 16:12:50 -08002537 * Informs listeners that this {@code Connection} has processed a character in the post-dial
2538 * started state. This is done when (a) the {@code Connection} is issuing a DTMF sequence;
Sailesh Nepal1ed85612015-01-31 15:17:19 -08002539 * and (b) it wishes to signal Telecom to play the corresponding DTMF tone locally.
Nancy Chen27d1c2d2014-12-15 16:12:50 -08002540 *
2541 * @param nextChar The DTMF character that was just processed by the {@code Connection}.
Nancy Chen27d1c2d2014-12-15 16:12:50 -08002542 */
Sailesh Nepal1ed85612015-01-31 15:17:19 -08002543 public final void setNextPostDialChar(char nextChar) {
Nancy Chen27d1c2d2014-12-15 16:12:50 -08002544 checkImmutable();
2545 for (Listener l : mListeners) {
2546 l.onPostDialChar(this, nextChar);
2547 }
2548 }
2549
2550 /**
Ihab Awadf8358972014-05-28 16:46:42 -07002551 * Requests that the framework play a ringback tone. This is to be invoked by implementations
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002552 * that do not play a ringback tone themselves in the connection's audio stream.
Ihab Awadf8358972014-05-28 16:46:42 -07002553 *
2554 * @param ringback Whether the ringback tone is to be played.
2555 */
Andrew Lee100e2932014-09-08 15:34:24 -07002556 public final void setRingbackRequested(boolean ringback) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002557 checkImmutable();
Andrew Lee100e2932014-09-08 15:34:24 -07002558 if (mRingbackRequested != ringback) {
2559 mRingbackRequested = ringback;
Santos Cordond34e5712014-08-05 18:54:03 +00002560 for (Listener l : mListeners) {
Andrew Lee100e2932014-09-08 15:34:24 -07002561 l.onRingbackRequested(this, ringback);
Santos Cordond34e5712014-08-05 18:54:03 +00002562 }
2563 }
Ihab Awadf8358972014-05-28 16:46:42 -07002564 }
2565
2566 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002567 * Sets the connection's capabilities as a bit mask of the {@code CAPABILITY_*} constants.
Sailesh Nepal1a7061b2014-07-09 21:03:20 -07002568 *
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002569 * @param connectionCapabilities The new connection capabilities.
Santos Cordonb6939982014-06-04 20:20:58 -07002570 */
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002571 public final void setConnectionCapabilities(int connectionCapabilities) {
2572 checkImmutable();
2573 if (mConnectionCapabilities != connectionCapabilities) {
2574 mConnectionCapabilities = connectionCapabilities;
Santos Cordond34e5712014-08-05 18:54:03 +00002575 for (Listener l : mListeners) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002576 l.onConnectionCapabilitiesChanged(this, mConnectionCapabilities);
Santos Cordond34e5712014-08-05 18:54:03 +00002577 }
2578 }
Santos Cordonb6939982014-06-04 20:20:58 -07002579 }
2580
2581 /**
Tyler Gunn720c6642016-03-22 09:02:47 -07002582 * Sets the connection's properties as a bit mask of the {@code PROPERTY_*} constants.
2583 *
2584 * @param connectionProperties The new connection properties.
2585 */
2586 public final void setConnectionProperties(int connectionProperties) {
2587 checkImmutable();
2588 if (mConnectionProperties != connectionProperties) {
2589 mConnectionProperties = connectionProperties;
2590 for (Listener l : mListeners) {
2591 l.onConnectionPropertiesChanged(this, mConnectionProperties);
2592 }
2593 }
2594 }
2595
2596 /**
Christine Hallstrom2830ce92016-11-30 16:06:42 -08002597 * Sets the supported audio routes.
2598 *
2599 * @param supportedAudioRoutes the supported audio routes as a bitmask.
2600 * See {@link CallAudioState}
2601 * @hide
2602 */
2603 public final void setSupportedAudioRoutes(int supportedAudioRoutes) {
2604 if ((supportedAudioRoutes
2605 & (CallAudioState.ROUTE_EARPIECE | CallAudioState.ROUTE_SPEAKER)) == 0) {
2606 throw new IllegalArgumentException(
2607 "supported audio routes must include either speaker or earpiece");
2608 }
2609
2610 if (mSupportedAudioRoutes != supportedAudioRoutes) {
2611 mSupportedAudioRoutes = supportedAudioRoutes;
2612 for (Listener l : mListeners) {
2613 l.onSupportedAudioRoutesChanged(this, mSupportedAudioRoutes);
2614 }
2615 }
2616 }
2617
2618 /**
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002619 * Tears down the Connection object.
Santos Cordonb6939982014-06-04 20:20:58 -07002620 */
Evan Charlton36a71342014-07-19 16:31:02 -07002621 public final void destroy() {
Jay Shrauner229e3822014-08-15 09:23:07 -07002622 for (Listener l : mListeners) {
2623 l.onDestroyed(this);
Santos Cordond34e5712014-08-05 18:54:03 +00002624 }
Santos Cordonb6939982014-06-04 20:20:58 -07002625 }
2626
2627 /**
Sailesh Nepal33aaae42014-07-07 22:49:44 -07002628 * Requests that the framework use VOIP audio mode for this connection.
2629 *
2630 * @param isVoip True if the audio mode is VOIP.
2631 */
2632 public final void setAudioModeIsVoip(boolean isVoip) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002633 checkImmutable();
Santos Cordond34e5712014-08-05 18:54:03 +00002634 mAudioModeIsVoip = isVoip;
2635 for (Listener l : mListeners) {
2636 l.onAudioModeIsVoipChanged(this, isVoip);
2637 }
Sailesh Nepal33aaae42014-07-07 22:49:44 -07002638 }
2639
2640 /**
Roshan Piuse927ec02015-07-15 15:47:21 -07002641 * Sets the time at which a call became active on this Connection. This is set only
2642 * when a conference call becomes active on this connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002643 * <p>
Tyler Gunnc9503d62020-01-27 10:30:51 -08002644 * This time corresponds to the date/time of connection and is stored in the call log in
2645 * {@link android.provider.CallLog.Calls#DATE}.
2646 * <p>
Tyler Gunnc63f9082019-10-15 13:19:26 -07002647 * Used by telephony to maintain calls associated with an IMS Conference.
Roshan Piuse927ec02015-07-15 15:47:21 -07002648 *
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002649 * @param connectTimeMillis The connection time, in milliseconds. Should be set using a value
2650 * obtained from {@link System#currentTimeMillis()}.
Roshan Piuse927ec02015-07-15 15:47:21 -07002651 *
2652 * @hide
2653 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002654 @SystemApi
Tyler Gunnc9503d62020-01-27 10:30:51 -08002655 @RequiresPermission(MODIFY_PHONE_STATE)
2656 public final void setConnectTimeMillis(@IntRange(from = 0) long connectTimeMillis) {
Roshan Piuse927ec02015-07-15 15:47:21 -07002657 mConnectTimeMillis = connectTimeMillis;
2658 }
2659
2660 /**
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002661 * Sets the time at which a call became active on this Connection. This is set only
2662 * when a conference call becomes active on this connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07002663 * <p>
Tyler Gunnc9503d62020-01-27 10:30:51 -08002664 * This time is used to establish the duration of a call. It uses
2665 * {@link SystemClock#elapsedRealtime()} to ensure that the call duration is not impacted by
2666 * time zone changes during a call. The difference between the current
2667 * {@link SystemClock#elapsedRealtime()} and the value set at the connection start time is used
2668 * to populate {@link android.provider.CallLog.Calls#DURATION} in the call log.
2669 * <p>
Tyler Gunnc63f9082019-10-15 13:19:26 -07002670 * Used by telephony to maintain calls associated with an IMS Conference.
Tyler Gunnc9503d62020-01-27 10:30:51 -08002671 *
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002672 * @param connectElapsedTimeMillis The connection time, in milliseconds. Stored in the format
2673 * {@link SystemClock#elapsedRealtime()}.
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002674 * @hide
2675 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002676 @SystemApi
Tyler Gunnc9503d62020-01-27 10:30:51 -08002677 @RequiresPermission(MODIFY_PHONE_STATE)
2678 public final void setConnectionStartElapsedRealtimeMillis(
2679 @ElapsedRealtimeLong long connectElapsedTimeMillis) {
Tyler Gunn3fa819c2017-08-04 09:27:26 -07002680 mConnectElapsedTimeMillis = connectElapsedTimeMillis;
2681 }
2682
2683 /**
Sailesh Nepale7ef59a2014-07-08 21:48:22 -07002684 * Sets the label and icon status to display in the in-call UI.
2685 *
2686 * @param statusHints The status label and icon to set.
2687 */
2688 public final void setStatusHints(StatusHints statusHints) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002689 checkImmutable();
Santos Cordond34e5712014-08-05 18:54:03 +00002690 mStatusHints = statusHints;
2691 for (Listener l : mListeners) {
2692 l.onStatusHintsChanged(this, statusHints);
2693 }
Sailesh Nepale7ef59a2014-07-08 21:48:22 -07002694 }
2695
2696 /**
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002697 * Sets the connections with which this connection can be conferenced.
2698 *
2699 * @param conferenceableConnections The set of connections this connection can conference with.
2700 */
2701 public final void setConferenceableConnections(List<Connection> conferenceableConnections) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002702 checkImmutable();
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002703 clearConferenceableList();
2704 for (Connection c : conferenceableConnections) {
2705 // If statement checks for duplicates in input. It makes it N^2 but we're dealing with a
2706 // small amount of items here.
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002707 if (!mConferenceables.contains(c)) {
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002708 c.addConnectionListener(mConnectionDeathListener);
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002709 mConferenceables.add(c);
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07002710 }
2711 }
2712 fireOnConferenceableConnectionsChanged();
2713 }
2714
2715 /**
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002716 * Similar to {@link #setConferenceableConnections(java.util.List)}, sets a list of connections
2717 * or conferences with which this connection can be conferenced.
2718 *
2719 * @param conferenceables The conferenceables.
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002720 */
Tyler Gunndf2cbc82015-04-20 09:13:01 -07002721 public final void setConferenceables(List<Conferenceable> conferenceables) {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002722 clearConferenceableList();
Tyler Gunndf2cbc82015-04-20 09:13:01 -07002723 for (Conferenceable c : conferenceables) {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002724 // If statement checks for duplicates in input. It makes it N^2 but we're dealing with a
2725 // small amount of items here.
2726 if (!mConferenceables.contains(c)) {
2727 if (c instanceof Connection) {
2728 Connection connection = (Connection) c;
2729 connection.addConnectionListener(mConnectionDeathListener);
2730 } else if (c instanceof Conference) {
2731 Conference conference = (Conference) c;
2732 conference.addListener(mConferenceDeathListener);
2733 }
2734 mConferenceables.add(c);
2735 }
2736 }
2737 fireOnConferenceableConnectionsChanged();
2738 }
2739
2740 /**
Tyler Gunnc63f9082019-10-15 13:19:26 -07002741 * Resets the CDMA connection time.
2742 * <p>
2743 * This is an implementation detail specific to legacy CDMA calls on mobile networks.
Mengjun Leng25707742017-07-04 11:10:37 +08002744 * @hide
Mengjun Leng25707742017-07-04 11:10:37 +08002745 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07002746 @SystemApi
Mengjun Leng25707742017-07-04 11:10:37 +08002747 public final void resetConnectionTime() {
2748 for (Listener l : mListeners) {
2749 l.onConnectionTimeReset(this);
2750 }
2751 }
2752
2753 /**
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002754 * Returns the connections or conferences with which this connection can be conferenced.
2755 */
Tyler Gunndf2cbc82015-04-20 09:13:01 -07002756 public final List<Conferenceable> getConferenceables() {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08002757 return mUnmodifiableConferenceables;
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002758 }
2759
Yorke Lee53463962015-08-04 16:07:19 -07002760 /**
Santos Cordon823fd3c2014-08-07 18:35:18 -07002761 * @hide
2762 */
2763 public final void setConnectionService(ConnectionService connectionService) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002764 checkImmutable();
Santos Cordon823fd3c2014-08-07 18:35:18 -07002765 if (mConnectionService != null) {
2766 Log.e(this, new Exception(), "Trying to set ConnectionService on a connection " +
2767 "which is already associated with another ConnectionService.");
2768 } else {
2769 mConnectionService = connectionService;
2770 }
2771 }
2772
2773 /**
2774 * @hide
2775 */
2776 public final void unsetConnectionService(ConnectionService connectionService) {
2777 if (mConnectionService != connectionService) {
2778 Log.e(this, new Exception(), "Trying to remove ConnectionService from a Connection " +
2779 "that does not belong to the ConnectionService.");
2780 } else {
2781 mConnectionService = null;
2782 }
2783 }
2784
2785 /**
2786 * Sets the conference that this connection is a part of. This will fail if the connection is
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002787 * already part of a conference. {@link #resetConference} to un-set the conference first.
Santos Cordon823fd3c2014-08-07 18:35:18 -07002788 *
2789 * @param conference The conference.
2790 * @return {@code true} if the conference was successfully set.
2791 * @hide
2792 */
2793 public final boolean setConference(Conference conference) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08002794 checkImmutable();
Santos Cordon823fd3c2014-08-07 18:35:18 -07002795 // We check to see if it is already part of another conference.
Santos Cordon0159ac02014-08-21 14:28:11 -07002796 if (mConference == null) {
Santos Cordon823fd3c2014-08-07 18:35:18 -07002797 mConference = conference;
Santos Cordon0159ac02014-08-21 14:28:11 -07002798 if (mConnectionService != null && mConnectionService.containsConference(conference)) {
2799 fireConferenceChanged();
2800 }
Santos Cordon823fd3c2014-08-07 18:35:18 -07002801 return true;
2802 }
2803 return false;
2804 }
2805
2806 /**
2807 * Resets the conference that this connection is a part of.
2808 * @hide
2809 */
2810 public final void resetConference() {
2811 if (mConference != null) {
Santos Cordon0159ac02014-08-21 14:28:11 -07002812 Log.d(this, "Conference reset");
Santos Cordon823fd3c2014-08-07 18:35:18 -07002813 mConference = null;
2814 fireConferenceChanged();
2815 }
2816 }
2817
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002818 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07002819 * Set some extras that can be associated with this {@code Connection}.
2820 * <p>
2821 * New or existing keys are replaced in the {@code Connection} extras. Keys which are no longer
2822 * in the new extras, but were present the last time {@code setExtras} was called are removed.
2823 * <p>
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07002824 * Alternatively you may use the {@link #putExtras(Bundle)}, and
2825 * {@link #removeExtras(String...)} methods to modify the extras.
2826 * <p>
Tyler Gunndee56a82016-03-23 16:06:34 -07002827 * No assumptions should be made as to how an In-Call UI or service will handle these extras.
Santos Cordon6b7f9552015-05-27 17:21:45 -07002828 * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
2829 *
2830 * @param extras The extras associated with this {@code Connection}.
2831 */
2832 public final void setExtras(@Nullable Bundle extras) {
2833 checkImmutable();
Tyler Gunndee56a82016-03-23 16:06:34 -07002834
2835 // Add/replace any new or changed extras values.
2836 putExtras(extras);
2837
2838 // If we have used "setExtras" in the past, compare the key set from the last invocation to
2839 // the current one and remove any keys that went away.
2840 if (mPreviousExtraKeys != null) {
2841 List<String> toRemove = new ArrayList<String>();
2842 for (String oldKey : mPreviousExtraKeys) {
Tyler Gunna8fb8ab2016-03-29 10:24:22 -07002843 if (extras == null || !extras.containsKey(oldKey)) {
Tyler Gunndee56a82016-03-23 16:06:34 -07002844 toRemove.add(oldKey);
2845 }
2846 }
2847 if (!toRemove.isEmpty()) {
2848 removeExtras(toRemove);
2849 }
2850 }
2851
2852 // Track the keys the last time set called setExtras. This way, the next time setExtras is
2853 // called we can see if the caller has removed any extras values.
2854 if (mPreviousExtraKeys == null) {
2855 mPreviousExtraKeys = new ArraySet<String>();
2856 }
2857 mPreviousExtraKeys.clear();
Tyler Gunna8fb8ab2016-03-29 10:24:22 -07002858 if (extras != null) {
2859 mPreviousExtraKeys.addAll(extras.keySet());
2860 }
Tyler Gunndee56a82016-03-23 16:06:34 -07002861 }
2862
2863 /**
2864 * Adds some extras to this {@code Connection}. Existing keys are replaced and new ones are
2865 * added.
2866 * <p>
2867 * No assumptions should be made as to how an In-Call UI or service will handle these extras.
2868 * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
2869 *
2870 * @param extras The extras to add.
2871 */
2872 public final void putExtras(@NonNull Bundle extras) {
2873 checkImmutable();
2874 if (extras == null) {
2875 return;
2876 }
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002877 // Creating a duplicate bundle so we don't have to synchronize on mExtrasLock while calling
2878 // the listeners.
2879 Bundle listenerExtras;
2880 synchronized (mExtrasLock) {
2881 if (mExtras == null) {
2882 mExtras = new Bundle();
2883 }
2884 mExtras.putAll(extras);
2885 listenerExtras = new Bundle(mExtras);
Tyler Gunndee56a82016-03-23 16:06:34 -07002886 }
Santos Cordon6b7f9552015-05-27 17:21:45 -07002887 for (Listener l : mListeners) {
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002888 // Create a new clone of the extras for each listener so that they don't clobber
2889 // each other
2890 l.onExtrasChanged(this, new Bundle(listenerExtras));
Santos Cordon6b7f9552015-05-27 17:21:45 -07002891 }
2892 }
2893
2894 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002895 * Removes extras from this {@code Connection}.
Tyler Gunndee56a82016-03-23 16:06:34 -07002896 *
Tyler Gunn071be6f2016-05-10 14:52:33 -07002897 * @param keys The keys of the extras to remove.
Tyler Gunndee56a82016-03-23 16:06:34 -07002898 */
2899 public final void removeExtras(List<String> keys) {
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002900 synchronized (mExtrasLock) {
2901 if (mExtras != null) {
2902 for (String key : keys) {
2903 mExtras.remove(key);
2904 }
Tyler Gunndee56a82016-03-23 16:06:34 -07002905 }
2906 }
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002907 List<String> unmodifiableKeys = Collections.unmodifiableList(keys);
Tyler Gunndee56a82016-03-23 16:06:34 -07002908 for (Listener l : mListeners) {
Brad Ebinger4fa6a012016-06-14 17:04:01 -07002909 l.onExtrasRemoved(this, unmodifiableKeys);
Tyler Gunndee56a82016-03-23 16:06:34 -07002910 }
2911 }
2912
2913 /**
Tyler Gunn071be6f2016-05-10 14:52:33 -07002914 * Removes extras from this {@code Connection}.
2915 *
2916 * @param keys The keys of the extras to remove.
2917 */
2918 public final void removeExtras(String ... keys) {
2919 removeExtras(Arrays.asList(keys));
2920 }
2921
2922 /**
Tyler Gunnf5035432017-01-09 09:43:12 -08002923 * Sets the audio route (speaker, bluetooth, etc...). When this request is honored, there will
2924 * be change to the {@link #getCallAudioState()}.
2925 * <p>
2926 * Used by self-managed {@link ConnectionService}s which wish to change the audio route for a
2927 * self-managed {@link Connection} (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.)
2928 * <p>
2929 * See also {@link InCallService#setAudioRoute(int)}.
2930 *
2931 * @param route The audio route to use (one of {@link CallAudioState#ROUTE_BLUETOOTH},
2932 * {@link CallAudioState#ROUTE_EARPIECE}, {@link CallAudioState#ROUTE_SPEAKER}, or
2933 * {@link CallAudioState#ROUTE_WIRED_HEADSET}).
2934 */
2935 public final void setAudioRoute(int route) {
2936 for (Listener l : mListeners) {
Hall Liua98f58b52017-11-07 17:59:28 -08002937 l.onAudioRouteChanged(this, route, null);
2938 }
2939 }
2940
2941 /**
Hall Liua98f58b52017-11-07 17:59:28 -08002942 * Request audio routing to a specific bluetooth device. Calling this method may result in
2943 * the device routing audio to a different bluetooth device than the one specified if the
2944 * bluetooth stack is unable to route audio to the requested device.
2945 * A list of available devices can be obtained via
2946 * {@link CallAudioState#getSupportedBluetoothDevices()}
2947 *
2948 * <p>
2949 * Used by self-managed {@link ConnectionService}s which wish to use bluetooth audio for a
2950 * self-managed {@link Connection} (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.)
2951 * <p>
Hall Liu2b6a6a32018-04-02 13:52:57 -07002952 * See also {@link InCallService#requestBluetoothAudio(BluetoothDevice)}
2953 * @param bluetoothDevice The bluetooth device to connect to.
Hall Liua98f58b52017-11-07 17:59:28 -08002954 */
Hall Liu2b6a6a32018-04-02 13:52:57 -07002955 public void requestBluetoothAudio(@NonNull BluetoothDevice bluetoothDevice) {
Hall Liua98f58b52017-11-07 17:59:28 -08002956 for (Listener l : mListeners) {
Hall Liu2b6a6a32018-04-02 13:52:57 -07002957 l.onAudioRouteChanged(this, CallAudioState.ROUTE_BLUETOOTH,
2958 bluetoothDevice.getAddress());
Tyler Gunnf5035432017-01-09 09:43:12 -08002959 }
2960 }
2961
2962 /**
Hall Liub64ac4c2017-02-06 10:49:48 -08002963 * Informs listeners that a previously requested RTT session via
2964 * {@link ConnectionRequest#isRequestingRtt()} or
Hall Liu37dfdb02017-12-04 14:19:30 -08002965 * {@link #onStartRtt(RttTextStream)} has succeeded.
Hall Liub64ac4c2017-02-06 10:49:48 -08002966 */
2967 public final void sendRttInitiationSuccess() {
2968 mListeners.forEach((l) -> l.onRttInitiationSuccess(Connection.this));
2969 }
2970
2971 /**
2972 * Informs listeners that a previously requested RTT session via
Hall Liu37dfdb02017-12-04 14:19:30 -08002973 * {@link ConnectionRequest#isRequestingRtt()} or {@link #onStartRtt(RttTextStream)}
Hall Liub64ac4c2017-02-06 10:49:48 -08002974 * has failed.
2975 * @param reason One of the reason codes defined in {@link RttModifyStatus}, with the
2976 * exception of {@link RttModifyStatus#SESSION_MODIFY_REQUEST_SUCCESS}.
Hall Liub64ac4c2017-02-06 10:49:48 -08002977 */
2978 public final void sendRttInitiationFailure(int reason) {
2979 mListeners.forEach((l) -> l.onRttInitiationFailure(Connection.this, reason));
2980 }
2981
2982 /**
2983 * Informs listeners that a currently active RTT session has been terminated by the remote
2984 * side of the coll.
Hall Liub64ac4c2017-02-06 10:49:48 -08002985 */
2986 public final void sendRttSessionRemotelyTerminated() {
2987 mListeners.forEach((l) -> l.onRttSessionRemotelyTerminated(Connection.this));
2988 }
2989
2990 /**
2991 * Informs listeners that the remote side of the call has requested an upgrade to include an
2992 * RTT session in the call.
Hall Liub64ac4c2017-02-06 10:49:48 -08002993 */
2994 public final void sendRemoteRttRequest() {
2995 mListeners.forEach((l) -> l.onRemoteRttRequest(Connection.this));
2996 }
2997
2998 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07002999 * Notifies this Connection that the {@link #getAudioState()} property has a new value.
Sailesh Nepal400cc482014-06-26 12:04:00 -07003000 *
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003001 * @param state The new connection audio state.
Yorke Lee4af59352015-05-13 14:14:54 -07003002 * @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.
3003 * @hide
Sailesh Nepal400cc482014-06-26 12:04:00 -07003004 */
Yorke Lee4af59352015-05-13 14:14:54 -07003005 @SystemApi
3006 @Deprecated
Nancy Chen354b2bd2014-09-08 18:27:26 -07003007 public void onAudioStateChanged(AudioState state) {}
Sailesh Nepal400cc482014-06-26 12:04:00 -07003008
3009 /**
Yorke Lee4af59352015-05-13 14:14:54 -07003010 * Notifies this Connection that the {@link #getCallAudioState()} property has a new value.
3011 *
3012 * @param state The new connection audio state.
3013 */
3014 public void onCallAudioStateChanged(CallAudioState state) {}
3015
3016 /**
Grace Jiae99fde92021-01-19 14:58:01 -08003017 * Inform this Connection when it will or will not be tracked by an {@link InCallService} which
3018 * can provide an InCall UI.
3019 * This is primarily intended for use by Connections reported by self-managed
3020 * {@link ConnectionService} which typically maintain their own UI.
3021 *
3022 * @param isUsingAlternativeUi Indicates whether an InCallService that can provide InCall UI is
3023 * currently tracking the self-managed call.
3024 */
3025 public void onUsingAlternativeUi(boolean isUsingAlternativeUi) {}
3026
3027 /**
3028 * Inform this Conenection when it will or will not be tracked by an non-UI
3029 * {@link InCallService}.
3030 *
3031 * @param isTracked Indicates whether an non-UI InCallService is currently tracking the
3032 * self-managed call.
3033 */
3034 public void onTrackedByNonUiService(boolean isTracked) {}
3035
3036 /**
Evan Charltonbf11f982014-07-20 22:06:28 -07003037 * Notifies this Connection of an internal state change. This method is called after the
3038 * state is changed.
Ihab Awadf8358972014-05-28 16:46:42 -07003039 *
Ihab Awadb19a0bc2014-08-07 19:46:01 -07003040 * @param state The new state, one of the {@code STATE_*} constants.
Ihab Awadf8358972014-05-28 16:46:42 -07003041 */
Nancy Chen354b2bd2014-09-08 18:27:26 -07003042 public void onStateChanged(int state) {}
Ihab Awadf8358972014-05-28 16:46:42 -07003043
3044 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07003045 * Notifies this Connection of a request to play a DTMF tone.
3046 *
3047 * @param c A DTMF character.
3048 */
Santos Cordonf2951102014-07-20 19:06:29 -07003049 public void onPlayDtmfTone(char c) {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003050
3051 /**
3052 * Notifies this Connection of a request to stop any currently playing DTMF tones.
3053 */
Santos Cordonf2951102014-07-20 19:06:29 -07003054 public void onStopDtmfTone() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003055
3056 /**
3057 * Notifies this Connection of a request to disconnect.
3058 */
Santos Cordonf2951102014-07-20 19:06:29 -07003059 public void onDisconnect() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003060
3061 /**
Tyler Gunn3b4b1dc2014-11-04 14:53:37 -08003062 * Notifies this Connection of a request to disconnect a participant of the conference managed
3063 * by the connection.
3064 *
3065 * @param endpoint the {@link Uri} of the participant to disconnect.
3066 * @hide
3067 */
3068 public void onDisconnectConferenceParticipant(Uri endpoint) {}
3069
3070 /**
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003071 * Notifies this Connection of a request to separate from its parent conference.
Santos Cordonb6939982014-06-04 20:20:58 -07003072 */
Santos Cordonf2951102014-07-20 19:06:29 -07003073 public void onSeparate() {}
Santos Cordonb6939982014-06-04 20:20:58 -07003074
3075 /**
Tyler Gunn0c62ef02020-02-11 14:39:43 -08003076 * Supports initiation of a conference call by directly adding participants to an ongoing call.
Ravi Paluri404babb2020-01-23 19:02:44 +05303077 *
3078 * @param participants with which conference call will be formed.
3079 */
3080 public void onAddConferenceParticipants(@NonNull List<Uri> participants) {}
3081
3082 /**
Ihab Awad542e0ea2014-05-16 10:22:16 -07003083 * Notifies this Connection of a request to abort.
3084 */
Santos Cordonf2951102014-07-20 19:06:29 -07003085 public void onAbort() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003086
3087 /**
3088 * Notifies this Connection of a request to hold.
3089 */
Santos Cordonf2951102014-07-20 19:06:29 -07003090 public void onHold() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003091
3092 /**
3093 * Notifies this Connection of a request to exit a hold state.
3094 */
Santos Cordonf2951102014-07-20 19:06:29 -07003095 public void onUnhold() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003096
3097 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07003098 * Notifies this Connection, which is in {@link #STATE_RINGING}, of
Santos Cordond34e5712014-08-05 18:54:03 +00003099 * a request to accept.
Tyler Gunn7c3ddcf2018-02-08 11:28:33 -08003100 * <p>
3101 * For managed {@link ConnectionService}s, this will be called when the user answers a call via
3102 * the default dialer's {@link InCallService}.
3103 * <p>
3104 * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
3105 * Telecom framework may request that the call is answered in the following circumstances:
3106 * <ul>
3107 * <li>The user chooses to answer an incoming call via a Bluetooth device.</li>
3108 * <li>A car mode {@link InCallService} is in use which has declared
3109 * {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest. Such an
3110 * {@link InCallService} will be able to see calls from self-managed
3111 * {@link ConnectionService}s, and will be able to display an incoming call UI on their
3112 * behalf.</li>
3113 * </ul>
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003114 * @param videoState The video state in which to answer the connection.
Ihab Awad542e0ea2014-05-16 10:22:16 -07003115 */
Santos Cordonf2951102014-07-20 19:06:29 -07003116 public void onAnswer(int videoState) {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003117
3118 /**
Ihab Awadb19a0bc2014-08-07 19:46:01 -07003119 * Notifies this Connection, which is in {@link #STATE_RINGING}, of
Tyler Gunnbe74de02014-08-29 14:51:48 -07003120 * a request to accept.
Tyler Gunn7c3ddcf2018-02-08 11:28:33 -08003121 * <p>
3122 * For managed {@link ConnectionService}s, this will be called when the user answers a call via
3123 * the default dialer's {@link InCallService}.
3124 * <p>
3125 * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
3126 * Telecom framework may request that the call is answered in the following circumstances:
3127 * <ul>
3128 * <li>The user chooses to answer an incoming call via a Bluetooth device.</li>
3129 * <li>A car mode {@link InCallService} is in use which has declared
3130 * {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest. Such an
3131 * {@link InCallService} will be able to see calls from self-managed
3132 * {@link ConnectionService}s, and will be able to display an incoming call UI on their
3133 * behalf.</li>
3134 * </ul>
Tyler Gunnbe74de02014-08-29 14:51:48 -07003135 */
3136 public void onAnswer() {
Tyler Gunn87b73f32015-06-03 10:09:59 -07003137 onAnswer(VideoProfile.STATE_AUDIO_ONLY);
Tyler Gunnbe74de02014-08-29 14:51:48 -07003138 }
3139
3140 /**
3141 * Notifies this Connection, which is in {@link #STATE_RINGING}, of
Pooja Jaind34698d2017-12-28 14:15:31 +05303142 * a request to deflect.
3143 */
3144 public void onDeflect(Uri address) {}
3145
3146 /**
3147 * Notifies this Connection, which is in {@link #STATE_RINGING}, of
Santos Cordond34e5712014-08-05 18:54:03 +00003148 * a request to reject.
Tyler Gunn7c3ddcf2018-02-08 11:28:33 -08003149 * <p>
3150 * For managed {@link ConnectionService}s, this will be called when the user rejects a call via
3151 * the default dialer's {@link InCallService}.
3152 * <p>
3153 * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
3154 * Telecom framework may request that the call is rejected in the following circumstances:
3155 * <ul>
3156 * <li>The user chooses to reject an incoming call via a Bluetooth device.</li>
3157 * <li>A car mode {@link InCallService} is in use which has declared
3158 * {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest. Such an
3159 * {@link InCallService} will be able to see calls from self-managed
3160 * {@link ConnectionService}s, and will be able to display an incoming call UI on their
3161 * behalf.</li>
3162 * </ul>
Ihab Awad542e0ea2014-05-16 10:22:16 -07003163 */
Santos Cordonf2951102014-07-20 19:06:29 -07003164 public void onReject() {}
Ihab Awad542e0ea2014-05-16 10:22:16 -07003165
Evan Charlton6dea4ac2014-06-03 14:07:13 -07003166 /**
Tyler Gunnfacfdee2020-01-23 13:10:37 -08003167 * Notifies this Connection, which is in {@link #STATE_RINGING}, of a request to reject.
3168 * <p>
3169 * For managed {@link ConnectionService}s, this will be called when the user rejects a call via
3170 * the default dialer's {@link InCallService} using {@link Call#reject(int)}.
3171 * @param rejectReason the reason the user provided for rejecting the call.
3172 */
3173 public void onReject(@android.telecom.Call.RejectReason int rejectReason) {
3174 // to be implemented by ConnectionService.
3175 }
3176
3177 /**
Hall Liu712acbe2016-03-14 16:38:56 -07003178 * Notifies this Connection, which is in {@link #STATE_RINGING}, of
3179 * a request to reject with a message.
Bryce Lee81901682015-08-28 16:38:02 -07003180 */
3181 public void onReject(String replyMessage) {}
3182
3183 /**
Ravi Palurif4b38e72020-02-05 12:35:41 +05303184 * Notifies this Connection, a request to transfer to a target number.
3185 * @param number the number to transfer this {@link Connection} to.
3186 * @param isConfirmationRequired when {@code true}, the {@link ConnectionService}
3187 * should wait until the transfer has successfully completed before disconnecting
3188 * the current {@link Connection}.
3189 * When {@code false}, the {@link ConnectionService} should signal the network to
3190 * perform the transfer, but should immediately disconnect the call regardless of
3191 * the outcome of the transfer.
3192 * @hide
3193 */
3194 public void onTransfer(@NonNull Uri number, boolean isConfirmationRequired) {}
3195
3196 /**
3197 * Notifies this Connection, a request to transfer to another Connection.
3198 * @param otherConnection the {@link Connection} to transfer this call to.
3199 * @hide
3200 */
3201 public void onTransfer(@NonNull Connection otherConnection) {}
3202
3203 /**
Tyler Gunn06f06162018-06-18 11:24:15 -07003204 * Notifies this Connection of a request to silence the ringer.
3205 * <p>
3206 * The ringer may be silenced by any of the following methods:
3207 * <ul>
3208 * <li>{@link TelecomManager#silenceRinger()}</li>
3209 * <li>The user presses the volume-down button while a call is ringing.</li>
3210 * </ul>
3211 * <p>
3212 * Self-managed {@link ConnectionService} implementations should override this method in their
3213 * {@link Connection} implementation and implement logic to silence their app's ringtone. If
3214 * your app set the ringtone as part of the incoming call {@link Notification} (see
3215 * {@link #onShowIncomingCallUi()}), it should re-post the notification now, except call
3216 * {@link android.app.Notification.Builder#setOnlyAlertOnce(boolean)} with {@code true}. This
3217 * will ensure the ringtone sound associated with your {@link android.app.NotificationChannel}
3218 * stops playing.
Bryce Leecac50772015-11-17 15:13:29 -08003219 */
3220 public void onSilence() {}
3221
3222 /**
Evan Charlton6dea4ac2014-06-03 14:07:13 -07003223 * Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.
3224 */
Santos Cordonf2951102014-07-20 19:06:29 -07003225 public void onPostDialContinue(boolean proceed) {}
Evan Charlton6dea4ac2014-06-03 14:07:13 -07003226
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003227 /**
3228 * Notifies this Connection of a request to pull an external call to the local device.
3229 * <p>
3230 * The {@link InCallService} issues a request to pull an external call to the local device via
3231 * {@link Call#pullExternalCall()}.
3232 * <p>
Tyler Gunn720c6642016-03-22 09:02:47 -07003233 * For a Connection to be pulled, both the {@link Connection#CAPABILITY_CAN_PULL_CALL}
3234 * capability and {@link Connection#PROPERTY_IS_EXTERNAL_CALL} property bits must be set.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003235 * <p>
Tyler Gunn720c6642016-03-22 09:02:47 -07003236 * For more information on external calls, see {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003237 */
3238 public void onPullExternalCall() {}
3239
3240 /**
3241 * Notifies this Connection of a {@link Call} event initiated from an {@link InCallService}.
3242 * <p>
3243 * The {@link InCallService} issues a Call event via {@link Call#sendCallEvent(String, Bundle)}.
3244 * <p>
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07003245 * Where possible, the Connection should make an attempt to handle {@link Call} events which
3246 * are part of the {@code android.telecom.*} namespace. The Connection should ignore any events
3247 * it does not wish to handle. Unexpected events should be handled gracefully, as it is
3248 * possible that a {@link InCallService} has defined its own Call events which a Connection is
3249 * not aware of.
3250 * <p>
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003251 * See also {@link Call#sendCallEvent(String, Bundle)}.
3252 *
3253 * @param event The call event.
3254 * @param extras Extras associated with the call event.
3255 */
3256 public void onCallEvent(String event, Bundle extras) {}
3257
Tyler Gunndee56a82016-03-23 16:06:34 -07003258 /**
Tyler Gunn79bc1ec2018-01-22 15:17:54 -08003259 * Notifies this {@link Connection} that a handover has completed.
3260 * <p>
3261 * A handover is initiated with {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int,
3262 * Bundle)} on the initiating side of the handover, and
3263 * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}.
3264 */
3265 public void onHandoverComplete() {}
3266
3267 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07003268 * Notifies this {@link Connection} of a change to the extras made outside the
3269 * {@link ConnectionService}.
3270 * <p>
3271 * These extras changes can originate from Telecom itself, or from an {@link InCallService} via
3272 * the {@link android.telecom.Call#putExtras(Bundle)} and
3273 * {@link Call#removeExtras(List)}.
3274 *
3275 * @param extras The new extras bundle.
3276 */
3277 public void onExtrasChanged(Bundle extras) {}
3278
Tyler Gunnf5035432017-01-09 09:43:12 -08003279 /**
3280 * Notifies this {@link Connection} that its {@link ConnectionService} is responsible for
3281 * displaying its incoming call user interface for the {@link Connection}.
3282 * <p>
3283 * Will only be called for incoming calls added via a self-managed {@link ConnectionService}
3284 * (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}), where the {@link ConnectionService}
3285 * should show its own incoming call user interface.
3286 * <p>
3287 * Where there are ongoing calls in other self-managed {@link ConnectionService}s, or in a
Tyler Gunn7c3ddcf2018-02-08 11:28:33 -08003288 * regular {@link ConnectionService}, and it is not possible to hold these other calls, the
3289 * Telecom framework will display its own incoming call user interface to allow the user to
3290 * choose whether to answer the new incoming call and disconnect other ongoing calls, or to
3291 * reject the new incoming call.
Tyler Gunn159f35c2017-03-02 09:28:37 -08003292 * <p>
3293 * You should trigger the display of the incoming call user interface for your application by
3294 * showing a {@link Notification} with a full-screen {@link Intent} specified.
Tyler Gunn06f06162018-06-18 11:24:15 -07003295 *
3296 * In your application code, you should create a {@link android.app.NotificationChannel} for
3297 * incoming call notifications from your app:
3298 * <pre><code>
3299 * NotificationChannel channel = new NotificationChannel(YOUR_CHANNEL_ID, "Incoming Calls",
3300 * NotificationManager.IMPORTANCE_MAX);
3301 * // other channel setup stuff goes here.
3302 *
3303 * // We'll use the default system ringtone for our incoming call notification channel. You can
3304 * // use your own audio resource here.
3305 * Uri ringtoneUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE);
3306 * channel.setSound(ringtoneUri, new AudioAttributes.Builder()
3307 * // Setting the AudioAttributes is important as it identifies the purpose of your
3308 * // notification sound.
3309 * .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
3310 * .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
3311 * .build());
3312 *
3313 * NotificationManager mgr = getSystemService(NotificationManager.class);
3314 * mgr.createNotificationChannel(channel);
3315 * </code></pre>
3316 * When it comes time to post a notification for your incoming call, ensure it uses your
3317 * incoming call {@link android.app.NotificationChannel}.
Tyler Gunn159f35c2017-03-02 09:28:37 -08003318 * <pre><code>
3319 * // Create an intent which triggers your fullscreen incoming call user interface.
3320 * Intent intent = new Intent(Intent.ACTION_MAIN, null);
3321 * intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
3322 * intent.setClass(context, YourIncomingCallActivity.class);
Ashwini Orugantif8191e82021-01-07 12:04:25 -08003323 * PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, PendingIntent.FLAG_MUTABLE_UNAUDITED);
Tyler Gunn159f35c2017-03-02 09:28:37 -08003324 *
3325 * // Build the notification as an ongoing high priority item; this ensures it will show as
3326 * // a heads up notification which slides down over top of the current content.
3327 * final Notification.Builder builder = new Notification.Builder(context);
3328 * builder.setOngoing(true);
3329 * builder.setPriority(Notification.PRIORITY_HIGH);
3330 *
3331 * // Set notification content intent to take user to fullscreen UI if user taps on the
3332 * // notification body.
3333 * builder.setContentIntent(pendingIntent);
3334 * // Set full screen intent to trigger display of the fullscreen UI when the notification
3335 * // manager deems it appropriate.
3336 * builder.setFullScreenIntent(pendingIntent, true);
3337 *
3338 * // Setup notification content.
3339 * builder.setSmallIcon( yourIconResourceId );
3340 * builder.setContentTitle("Your notification title");
3341 * builder.setContentText("Your notification content.");
3342 *
Tyler Gunn06f06162018-06-18 11:24:15 -07003343 * // Set notification as insistent to cause your ringtone to loop.
3344 * Notification notification = builder.build();
3345 * notification.flags |= Notification.FLAG_INSISTENT;
Tyler Gunn159f35c2017-03-02 09:28:37 -08003346 *
Tyler Gunn06f06162018-06-18 11:24:15 -07003347 * // Use builder.addAction(..) to add buttons to answer or reject the call.
Tyler Gunn159f35c2017-03-02 09:28:37 -08003348 * NotificationManager notificationManager = mContext.getSystemService(
3349 * NotificationManager.class);
Tyler Gunn06f06162018-06-18 11:24:15 -07003350 * notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, notification);
Tyler Gunn159f35c2017-03-02 09:28:37 -08003351 * </code></pre>
Tyler Gunnf5035432017-01-09 09:43:12 -08003352 */
3353 public void onShowIncomingCallUi() {}
3354
Hall Liub64ac4c2017-02-06 10:49:48 -08003355 /**
3356 * Notifies this {@link Connection} that the user has requested an RTT session.
3357 * The connection service should call {@link #sendRttInitiationSuccess} or
3358 * {@link #sendRttInitiationFailure} to inform Telecom of the success or failure of the
3359 * request, respectively.
3360 * @param rttTextStream The object that should be used to send text to or receive text from
3361 * the in-call app.
Hall Liub64ac4c2017-02-06 10:49:48 -08003362 */
3363 public void onStartRtt(@NonNull RttTextStream rttTextStream) {}
3364
3365 /**
3366 * Notifies this {@link Connection} that it should terminate any existing RTT communication
3367 * channel. No response to Telecom is needed for this method.
Hall Liub64ac4c2017-02-06 10:49:48 -08003368 */
3369 public void onStopRtt() {}
3370
3371 /**
3372 * Notifies this connection of a response to a previous remotely-initiated RTT upgrade
3373 * request sent via {@link #sendRemoteRttRequest}. Acceptance of the request is
3374 * indicated by the supplied {@link RttTextStream} being non-null, and rejection is
3375 * indicated by {@code rttTextStream} being {@code null}
Hall Liub64ac4c2017-02-06 10:49:48 -08003376 * @param rttTextStream The object that should be used to send text to or receive text from
3377 * the in-call app.
3378 */
3379 public void handleRttUpgradeResponse(@Nullable RttTextStream rttTextStream) {}
3380
Hall Liu49cabcc2021-01-15 11:41:48 -08003381 /**
3382 * Indicates that call filtering in Telecom is complete
3383 *
3384 * This method is called for a connection created via
3385 * {@link ConnectionService#onCreateIncomingConnection} when call filtering completes in
3386 * Telecom, including checking the blocked number db, per-contact settings, and custom call
3387 * filtering apps.
3388 *
3389 * @param isBlocked {@code true} if the call was blocked, {@code false} otherwise. If this is
3390 * {@code true}, {@link #onDisconnect()} will be called soon after
3391 * this is called.
3392 * @param isInContacts Indicates whether the caller is in the user's contacts list.
3393 * @hide
3394 */
3395 @SystemApi
3396 @RequiresPermission(Manifest.permission.READ_CONTACTS)
3397 public void onCallFilteringCompleted(boolean isBlocked, boolean isInContacts) { }
3398
Ihab Awadb19a0bc2014-08-07 19:46:01 -07003399 static String toLogSafePhoneNumber(String number) {
3400 // For unknown number, log empty string.
3401 if (number == null) {
3402 return "";
3403 }
3404
3405 if (PII_DEBUG) {
3406 // When PII_DEBUG is true we emit PII.
3407 return number;
3408 }
3409
3410 // Do exactly same thing as Uri#toSafeString() does, which will enable us to compare
3411 // sanitized phone numbers.
3412 StringBuilder builder = new StringBuilder();
3413 for (int i = 0; i < number.length(); i++) {
3414 char c = number.charAt(i);
3415 if (c == '-' || c == '@' || c == '.') {
3416 builder.append(c);
3417 } else {
3418 builder.append('x');
3419 }
3420 }
3421 return builder.toString();
3422 }
3423
Ihab Awad542e0ea2014-05-16 10:22:16 -07003424 private void setState(int state) {
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003425 checkImmutable();
Ihab Awad6107bab2014-08-18 09:23:25 -07003426 if (mState == STATE_DISCONNECTED && mState != state) {
3427 Log.d(this, "Connection already DISCONNECTED; cannot transition out of this state.");
Evan Charltonbf11f982014-07-20 22:06:28 -07003428 return;
Sailesh Nepal400cc482014-06-26 12:04:00 -07003429 }
Evan Charltonbf11f982014-07-20 22:06:28 -07003430 if (mState != state) {
3431 Log.d(this, "setState: %s", stateToString(state));
3432 mState = state;
Nancy Chen354b2bd2014-09-08 18:27:26 -07003433 onStateChanged(state);
Evan Charltonbf11f982014-07-20 22:06:28 -07003434 for (Listener l : mListeners) {
3435 l.onStateChanged(this, state);
3436 }
Evan Charltonbf11f982014-07-20 22:06:28 -07003437 }
3438 }
3439
Sailesh Nepalcf7020b2014-08-20 10:07:19 -07003440 private static class FailureSignalingConnection extends Connection {
Ihab Awad90e34e32014-12-01 16:23:17 -08003441 private boolean mImmutable = false;
Andrew Lee7f3d41f2014-09-11 17:33:16 -07003442 public FailureSignalingConnection(DisconnectCause disconnectCause) {
3443 setDisconnected(disconnectCause);
Tyler Gunn2915af72020-03-06 11:36:21 -08003444 mImmutable = true;
Ihab Awad6107bab2014-08-18 09:23:25 -07003445 }
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003446
3447 public void checkImmutable() {
Ihab Awad90e34e32014-12-01 16:23:17 -08003448 if (mImmutable) {
3449 throw new UnsupportedOperationException("Connection is immutable");
3450 }
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003451 }
Ihab Awad6107bab2014-08-18 09:23:25 -07003452 }
3453
Evan Charltonbf11f982014-07-20 22:06:28 -07003454 /**
Ihab Awad6107bab2014-08-18 09:23:25 -07003455 * Return a {@code Connection} which represents a failed connection attempt. The returned
Andrew Lee7f3d41f2014-09-11 17:33:16 -07003456 * {@code Connection} will have a {@link android.telecom.DisconnectCause} and as specified,
3457 * and a {@link #getState()} of {@link #STATE_DISCONNECTED}.
Ihab Awad6107bab2014-08-18 09:23:25 -07003458 * <p>
3459 * The returned {@code Connection} can be assumed to {@link #destroy()} itself when appropriate,
3460 * so users of this method need not maintain a reference to its return value to destroy it.
Evan Charltonbf11f982014-07-20 22:06:28 -07003461 *
Andrew Lee7f3d41f2014-09-11 17:33:16 -07003462 * @param disconnectCause The disconnect cause, ({@see android.telecomm.DisconnectCause}).
Ihab Awad6107bab2014-08-18 09:23:25 -07003463 * @return A {@code Connection} which indicates failure.
Evan Charltonbf11f982014-07-20 22:06:28 -07003464 */
Andrew Lee7f3d41f2014-09-11 17:33:16 -07003465 public static Connection createFailedConnection(DisconnectCause disconnectCause) {
3466 return new FailureSignalingConnection(disconnectCause);
Evan Charltonbf11f982014-07-20 22:06:28 -07003467 }
3468
Evan Charltonbf11f982014-07-20 22:06:28 -07003469 /**
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003470 * Override to throw an {@link UnsupportedOperationException} if this {@code Connection} is
3471 * not intended to be mutated, e.g., if it is a marker for failure. Only for framework use;
3472 * this should never be un-@hide-den.
3473 *
3474 * @hide
3475 */
3476 public void checkImmutable() {}
3477
3478 /**
Ihab Awad6107bab2014-08-18 09:23:25 -07003479 * Return a {@code Connection} which represents a canceled connection attempt. The returned
3480 * {@code Connection} will have state {@link #STATE_DISCONNECTED}, and cannot be moved out of
3481 * that state. This connection should not be used for anything, and no other
3482 * {@code Connection}s should be attempted.
3483 * <p>
Ihab Awad6107bab2014-08-18 09:23:25 -07003484 * so users of this method need not maintain a reference to its return value to destroy it.
Evan Charltonbf11f982014-07-20 22:06:28 -07003485 *
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003486 * @return A {@code Connection} which indicates that the underlying connection should
3487 * be canceled.
Evan Charltonbf11f982014-07-20 22:06:28 -07003488 */
Ihab Awadb19a0bc2014-08-07 19:46:01 -07003489 public static Connection createCanceledConnection() {
Andrew Lee7f3d41f2014-09-11 17:33:16 -07003490 return new FailureSignalingConnection(new DisconnectCause(DisconnectCause.CANCELED));
Ihab Awad542e0ea2014-05-16 10:22:16 -07003491 }
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003492
Ihab Awad5c9c86e2014-11-12 13:41:16 -08003493 private final void fireOnConferenceableConnectionsChanged() {
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003494 for (Listener l : mListeners) {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08003495 l.onConferenceablesChanged(this, getConferenceables());
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003496 }
3497 }
3498
Santos Cordon823fd3c2014-08-07 18:35:18 -07003499 private final void fireConferenceChanged() {
3500 for (Listener l : mListeners) {
3501 l.onConferenceChanged(this, mConference);
3502 }
3503 }
3504
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003505 private final void clearConferenceableList() {
Tyler Gunndf2cbc82015-04-20 09:13:01 -07003506 for (Conferenceable c : mConferenceables) {
Tyler Gunn6d76ca02014-11-17 15:49:51 -08003507 if (c instanceof Connection) {
3508 Connection connection = (Connection) c;
3509 connection.removeConnectionListener(mConnectionDeathListener);
3510 } else if (c instanceof Conference) {
3511 Conference conference = (Conference) c;
3512 conference.removeListener(mConferenceDeathListener);
3513 }
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003514 }
Tyler Gunn6d76ca02014-11-17 15:49:51 -08003515 mConferenceables.clear();
Santos Cordon7c7bc7f2014-07-28 18:15:48 -07003516 }
Tyler Gunn3bffcf72014-10-28 13:51:27 -07003517
3518 /**
Tyler Gunndee56a82016-03-23 16:06:34 -07003519 * Handles a change to extras received from Telecom.
3520 *
3521 * @param extras The new extras.
3522 * @hide
3523 */
3524 final void handleExtrasChanged(Bundle extras) {
Brad Ebinger4fa6a012016-06-14 17:04:01 -07003525 Bundle b = null;
3526 synchronized (mExtrasLock) {
3527 mExtras = extras;
3528 if (mExtras != null) {
3529 b = new Bundle(mExtras);
3530 }
3531 }
3532 onExtrasChanged(b);
Tyler Gunndee56a82016-03-23 16:06:34 -07003533 }
3534
3535 /**
Tyler Gunnc63f9082019-10-15 13:19:26 -07003536 * Called by a {@link ConnectionService} to notify Telecom that a {@link Conference#onMerge()}
3537 * request failed.
Anthony Lee17455a32015-04-24 15:25:29 -07003538 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07003539 public final void notifyConferenceMergeFailed() {
Anthony Lee17455a32015-04-24 15:25:29 -07003540 for (Listener l : mListeners) {
3541 l.onConferenceMergeFailed(this);
3542 }
3543 }
3544
3545 /**
Srikanth Chintalafcb15012017-05-04 20:58:34 +05303546 * Notifies listeners when phone account is changed. For example, when the PhoneAccount is
3547 * changed due to an emergency call being redialed.
3548 * @param pHandle The new PhoneAccountHandle for this connection.
3549 * @hide
3550 */
3551 public void notifyPhoneAccountChanged(PhoneAccountHandle pHandle) {
3552 for (Listener l : mListeners) {
3553 l.onPhoneAccountChanged(this, pHandle);
3554 }
3555 }
3556
3557 /**
Pengquan Meng70c9885332017-10-02 18:09:03 -07003558 * Sets the {@link PhoneAccountHandle} associated with this connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07003559 * <p>
3560 * Used by the Telephony {@link ConnectionService} to handle changes to the {@link PhoneAccount}
3561 * which take place after call initiation (important for emergency calling scenarios).
Pengquan Meng70c9885332017-10-02 18:09:03 -07003562 *
Tyler Gunnc63f9082019-10-15 13:19:26 -07003563 * @param phoneAccountHandle the phone account handle to set.
Pengquan Meng70c9885332017-10-02 18:09:03 -07003564 * @hide
3565 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07003566 @SystemApi
3567 public void setPhoneAccountHandle(@NonNull PhoneAccountHandle phoneAccountHandle) {
Pengquan Meng70c9885332017-10-02 18:09:03 -07003568 if (mPhoneAccountHandle != phoneAccountHandle) {
3569 mPhoneAccountHandle = phoneAccountHandle;
3570 notifyPhoneAccountChanged(phoneAccountHandle);
3571 }
3572 }
3573
3574 /**
3575 * Returns the {@link PhoneAccountHandle} associated with this connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07003576 * <p>
3577 * Used by the Telephony {@link ConnectionService} to handle changes to the {@link PhoneAccount}
3578 * which take place after call initiation (important for emergency calling scenarios).
Pengquan Meng70c9885332017-10-02 18:09:03 -07003579 *
Tyler Gunnc63f9082019-10-15 13:19:26 -07003580 * @return the phone account handle specified via
3581 * {@link #setPhoneAccountHandle(PhoneAccountHandle)}, or {@code null} if none was set.
Pengquan Meng70c9885332017-10-02 18:09:03 -07003582 * @hide
3583 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07003584 @SystemApi
3585 public @Nullable PhoneAccountHandle getPhoneAccountHandle() {
Pengquan Meng70c9885332017-10-02 18:09:03 -07003586 return mPhoneAccountHandle;
3587 }
3588
3589 /**
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07003590 * Sends an event associated with this {@code Connection} with associated event extras to the
3591 * {@link InCallService}.
3592 * <p>
3593 * Connection events are used to communicate point in time information from a
3594 * {@link ConnectionService} to a {@link InCallService} implementations. An example of a
3595 * custom connection event includes notifying the UI when a WIFI call has been handed over to
3596 * LTE, which the InCall UI might use to inform the user that billing charges may apply. The
3597 * Android Telephony framework will send the {@link #EVENT_CALL_MERGE_FAILED} connection event
3598 * when a call to {@link Call#mergeConference()} has failed to complete successfully. A
3599 * connection event could also be used to trigger UI in the {@link InCallService} which prompts
3600 * the user to make a choice (e.g. whether they want to incur roaming costs for making a call),
3601 * which is communicated back via {@link Call#sendCallEvent(String, Bundle)}.
3602 * <p>
3603 * Events are exposed to {@link InCallService} implementations via
3604 * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
3605 * <p>
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003606 * No assumptions should be made as to how an In-Call UI or service will handle these events.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07003607 * The {@link ConnectionService} must assume that the In-Call UI could even chose to ignore
3608 * some events altogether.
3609 * <p>
3610 * Events should be fully qualified (e.g. {@code com.example.event.MY_EVENT}) to avoid
3611 * conflicts between {@link ConnectionService} implementations. Further, custom
3612 * {@link ConnectionService} implementations shall not re-purpose events in the
3613 * {@code android.*} namespace, nor shall they define new event types in this namespace. When
3614 * defining a custom event type, ensure the contents of the extras {@link Bundle} is clearly
3615 * defined. Extra keys for this bundle should be named similar to the event type (e.g.
3616 * {@code com.example.extra.MY_EXTRA}).
3617 * <p>
3618 * When defining events and the associated extras, it is important to keep their behavior
3619 * consistent when the associated {@link ConnectionService} is updated. Support for deprecated
3620 * events/extras should me maintained to ensure backwards compatibility with older
3621 * {@link InCallService} implementations which were built to support the older behavior.
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -08003622 *
3623 * @param event The connection event.
Tyler Gunn9c0eb0b2016-06-29 11:23:25 -07003624 * @param extras Optional bundle containing extra information associated with the event.
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -08003625 */
Tyler Gunn876dbfb2016-03-14 15:18:07 -07003626 public void sendConnectionEvent(String event, Bundle extras) {
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -08003627 for (Listener l : mListeners) {
Tyler Gunna8fb8ab2016-03-29 10:24:22 -07003628 l.onConnectionEvent(this, event, extras);
Tyler Gunnbd1eb1f2016-02-16 14:36:20 -08003629 }
3630 }
Tyler Gunn6986a632019-06-25 13:45:32 -07003631
3632 /**
3633 * @return The direction of the call.
3634 * @hide
3635 */
3636 public final @Call.Details.CallDirection int getCallDirection() {
3637 return mCallDirection;
3638 }
3639
3640 /**
3641 * Sets the direction of this connection.
Tyler Gunnc63f9082019-10-15 13:19:26 -07003642 * <p>
3643 * Used when calling {@link ConnectionService#addExistingConnection} to specify the existing
3644 * call direction.
3645 *
Tyler Gunn6986a632019-06-25 13:45:32 -07003646 * @param callDirection The direction of this connection.
3647 * @hide
3648 */
Tyler Gunnc63f9082019-10-15 13:19:26 -07003649 @SystemApi
Tyler Gunn6986a632019-06-25 13:45:32 -07003650 public void setCallDirection(@Call.Details.CallDirection int callDirection) {
3651 mCallDirection = callDirection;
3652 }
Tyler Gunnd57d76c2019-09-24 14:53:23 -07003653
3654 /**
3655 * Gets the verification status for the phone number of an incoming call as identified in
3656 * ATIS-1000082.
3657 * @return the verification status.
3658 */
Tyler Gunna131d6e2020-02-13 14:53:28 -08003659 public final @VerificationStatus int getCallerNumberVerificationStatus() {
Tyler Gunnd57d76c2019-09-24 14:53:23 -07003660 return mCallerNumberVerificationStatus;
3661 }
3662
3663 /**
3664 * Sets the verification status for the phone number of an incoming call as identified in
3665 * ATIS-1000082.
3666 * <p>
3667 * This property can only be set at the time of creation of a {@link Connection} being returned
3668 * by
3669 * {@link ConnectionService#onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)}.
3670 */
Tyler Gunna131d6e2020-02-13 14:53:28 -08003671 public final void setCallerNumberVerificationStatus(
Tyler Gunnd57d76c2019-09-24 14:53:23 -07003672 @VerificationStatus int callerNumberVerificationStatus) {
3673 mCallerNumberVerificationStatus = callerNumberVerificationStatus;
3674 }
Ihab Awad542e0ea2014-05-16 10:22:16 -07003675}