content: /*
   * Copyright (C) 2014 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.telecom;
  
  import android.annotation.NonNull;
  import android.annotation.Nullable;
  import android.annotation.SystemApi;
  import android.annotation.UnsupportedAppUsage;
  import android.app.Notification;
  import android.bluetooth.BluetoothDevice;
  import android.content.Intent;
  import android.hardware.camera2.CameraManager;
  import android.net.Uri;
  import android.os.Binder;
  import android.os.Bundle;
  import android.os.Handler;
  import android.os.IBinder;
  import android.os.Looper;
  import android.os.Message;
  import android.os.ParcelFileDescriptor;
  import android.os.RemoteException;
  import android.os.SystemClock;
  import android.telephony.ServiceState;
  import android.telephony.TelephonyManager;
  import android.util.ArraySet;
  import android.view.Surface;
  
  import com.android.internal.os.SomeArgs;
  import com.android.internal.telecom.IVideoCallback;
  import com.android.internal.telecom.IVideoProvider;
  
  import java.io.FileInputStream;
  import java.io.FileOutputStream;
  import java.io.IOException;
  import java.io.InputStreamReader;
  import java.io.OutputStreamWriter;
  import java.nio.channels.Channels;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collections;
  import java.util.List;
  import java.util.Set;
  import java.util.concurrent.ConcurrentHashMap;
  
  /**
   * Represents a phone call or connection to a remote endpoint that carries voice and/or video
   * traffic.
   * <p>
   * Implementations create a custom subclass of {@code Connection} and return it to the framework
   * as the return value of
   * {@link ConnectionService#onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)}
   * or
   * {@link ConnectionService#onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}.
   * Implementations are then responsible for updating the state of the {@code Connection}, and
   * must call {@link #destroy()} to signal to the framework that the {@code Connection} is no
   * longer used and associated resources may be recovered.
   * <p>
   * Subclasses of {@code Connection} override the {@code on*} methods to provide the the
   * {@link ConnectionService}'s implementation of calling functionality.  The {@code on*} methods are
   * called by Telecom to inform an instance of a {@code Connection} of actions specific to that
   * {@code Connection} instance.
   * <p>
   * Basic call support requires overriding the following methods: {@link #onAnswer()},
   * {@link #onDisconnect()}, {@link #onReject()}, {@link #onAbort()}
   * <p>
   * Where a {@code Connection} has {@link #CAPABILITY_SUPPORT_HOLD}, the {@link #onHold()} and
   * {@link #onUnhold()} methods should be overridden to provide hold support for the
   * {@code Connection}.
   * <p>
   * Where a {@code Connection} supports a variation of video calling (e.g. the
   * {@code CAPABILITY_SUPPORTS_VT_*} capability bits), {@link #onAnswer(int)} should be overridden
   * to support answering a call as a video call.
   * <p>
   * Where a {@code Connection} has {@link #PROPERTY_IS_EXTERNAL_CALL} and
   * {@link #CAPABILITY_CAN_PULL_CALL}, {@link #onPullExternalCall()} should be overridden to provide
   * support for pulling the external call.
   * <p>
   * Where a {@code Connection} supports conference calling {@link #onSeparate()} should be
   * overridden.
   * <p>
   * There are a number of other {@code on*} methods which a {@code Connection} can choose to
   * implement, depending on whether it is concerned with the associated calls from Telecom.  If,
   * for example, call events from a {@link InCallService} are handled,
   * {@link #onCallEvent(String, Bundle)} should be overridden.  Another example is
   * {@link #onExtrasChanged(Bundle)}, which should be overridden if the {@code Connection} wishes to
   * make use of extra information provided via the {@link Call#putExtras(Bundle)} and
   * {@link Call#removeExtras(String...)} methods.
   */
  public abstract class Connection extends Conferenceable {
  
      /**
       * The connection is initializing. This is generally the first state for a {@code Connection}
       * returned by a {@link ConnectionService}.
       */
      public static final int STATE_INITIALIZING = 0;
  
      /**
       * The connection is new and not connected.
       */
      public static final int STATE_NEW = 1;
  
      /**
       * An incoming connection is in the ringing state. During this state, the user's ringer or
       * vibration feature will be activated.
       */
      public static final int STATE_RINGING = 2;
  
      /**
       * An outgoing connection is in the dialing state. In this state the other party has not yet
       * answered the call and the user traditionally hears a ringback tone.
       */
      public static final int STATE_DIALING = 3;
  
      /**
       * A connection is active. Both parties are connected to the call and can actively communicate.
       */
      public static final int STATE_ACTIVE = 4;
  
      /**
       * A connection is on hold.
       */
      public static final int STATE_HOLDING = 5;
  
      /**
       * A connection has been disconnected. This is the final state once the user has been
       * disconnected from a call either locally, remotely or by an error in the service.
       */
      public static final int STATE_DISCONNECTED = 6;
  
      /**
       * The state of an external connection which is in the process of being pulled from a remote
       * device to the local device.
       * <p>
       * A connection can only be in this state if the {@link #PROPERTY_IS_EXTERNAL_CALL} property and
       * {@link #CAPABILITY_CAN_PULL_CALL} capability bits are set on the connection.
       */
      public static final int STATE_PULLING_CALL = 7;
  
      /**
       * Connection can currently be put on hold or unheld. This is distinct from
       * {@link #CAPABILITY_SUPPORT_HOLD} in that although a connection may support 'hold' most times,
       * it does not at the moment support the function. This can be true while the call is in the
       * state {@link #STATE_DIALING}, for example. During this condition, an in-call UI may
       * display a disabled 'hold' button.
       */
      public static final int CAPABILITY_HOLD = 0x00000001;
  
      /** Connection supports the hold feature. */
      public static final int CAPABILITY_SUPPORT_HOLD = 0x00000002;
  
      /**
       * Connections within a conference can be merged. A {@link ConnectionService} has the option to
       * add a {@link Conference} before the child {@link Connection}s are merged. This is how
       * CDMA-based {@link Connection}s are implemented. For these unmerged {@link Conference}s, this
       * capability allows a merge button to be shown while the conference is in the foreground
       * of the in-call UI.
       * <p>
       * This is only intended for use by a {@link Conference}.
       */
      public static final int CAPABILITY_MERGE_CONFERENCE = 0x00000004;
  
      /**
       * Connections within a conference can be swapped between foreground and background.
       * See {@link #CAPABILITY_MERGE_CONFERENCE} for additional information.
       * <p>
       * This is only intended for use by a {@link Conference}.
       */
      public static final int CAPABILITY_SWAP_CONFERENCE = 0x00000008;
  
      /**
       * @hide
       */
      public static final int CAPABILITY_UNUSED = 0x00000010;
  
      /** Connection supports responding via text option. */
      public static final int CAPABILITY_RESPOND_VIA_TEXT = 0x00000020;
  
      /** Connection can be muted. */
      public static final int CAPABILITY_MUTE = 0x00000040;
  
      /**
       * Connection supports conference management. This capability only applies to
       * {@link Conference}s which can have {@link Connection}s as children.
       */
      public static final int CAPABILITY_MANAGE_CONFERENCE = 0x00000080;
  
      /**
       * Local device supports receiving video.
       */
      public static final int CAPABILITY_SUPPORTS_VT_LOCAL_RX = 0x00000100;
  
      /**
       * Local device supports transmitting video.
       */
      public static final int CAPABILITY_SUPPORTS_VT_LOCAL_TX = 0x00000200;
  
      /**
       * Local device supports bidirectional video calling.
       */
      public static final int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL =
              CAPABILITY_SUPPORTS_VT_LOCAL_RX | CAPABILITY_SUPPORTS_VT_LOCAL_TX;
  
      /**
       * Remote device supports receiving video.
       */
      public static final int CAPABILITY_SUPPORTS_VT_REMOTE_RX = 0x00000400;
  
      /**
       * Remote device supports transmitting video.
       */
      public static final int CAPABILITY_SUPPORTS_VT_REMOTE_TX = 0x00000800;
  
      /**
       * Remote device supports bidirectional video calling.
       */
      public static final int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL =
              CAPABILITY_SUPPORTS_VT_REMOTE_RX | CAPABILITY_SUPPORTS_VT_REMOTE_TX;
  
      /**
       * Connection is able to be separated from its parent {@code Conference}, if any.
       */
      public static final int CAPABILITY_SEPARATE_FROM_CONFERENCE = 0x00001000;
  
      /**
       * Connection is able to be individually disconnected when in a {@code Conference}.
       */
      public static final int CAPABILITY_DISCONNECT_FROM_CONFERENCE = 0x00002000;
  
      /**
       * Un-used.
       * @hide
       */
      public static final int CAPABILITY_UNUSED_2 = 0x00004000;
  
      /**
       * Un-used.
       * @hide
       */
      public static final int CAPABILITY_UNUSED_3 = 0x00008000;
  
      /**
       * Un-used.
       * @hide
       */
      public static final int CAPABILITY_UNUSED_4 = 0x00010000;
  
      /**
       * Un-used.
       * @hide
       */
      public static final int CAPABILITY_UNUSED_5 = 0x00020000;
  
      /**
       * Speed up audio setup for MT call.
       * @hide
       */
      public static final int CAPABILITY_SPEED_UP_MT_AUDIO = 0x00040000;
  
      /**
       * Call can be upgraded to a video call.
       * @deprecated Use {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
       * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL} to indicate for a call whether or not
       * video calling is supported.
       */
      public static final int CAPABILITY_CAN_UPGRADE_TO_VIDEO = 0x00080000;
  
      /**
       * For video calls, indicates whether the outgoing video for the call can be paused using
       * the {@link android.telecom.VideoProfile#STATE_PAUSED} VideoState.
       */
      public static final int CAPABILITY_CAN_PAUSE_VIDEO = 0x00100000;
  
      /**
       * For a conference, indicates the conference will not have child connections.
       * <p>
       * An example of a conference with child connections is a GSM conference call, where the radio
       * retains connections to the individual participants of the conference.  Another example is an
       * IMS conference call where conference event package functionality is supported; in this case
       * the conference server ensures the radio is aware of the participants in the conference, which
       * are represented by child connections.
       * <p>
       * An example of a conference with no child connections is an IMS conference call with no
       * conference event package support.  Such a conference is represented by the radio as a single
       * connection to the IMS conference server.
       * <p>
       * Indicating whether a conference has children or not is important to help user interfaces
       * visually represent a conference.  A conference with no children, for example, will have the
       * conference connection shown in the list of calls on a Bluetooth device, where if the
       * conference has children, only the children will be shown in the list of calls on a Bluetooth
       * device.
       * @hide
       */
      public static final int CAPABILITY_CONFERENCE_HAS_NO_CHILDREN = 0x00200000;
  
      /**
       * Indicates that the connection itself wants to handle any sort of reply response, rather than
       * relying on SMS.
       */
      public static final int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION = 0x00400000;
  
      /**
       * When set, prevents a video call from being downgraded to an audio-only call.
       * <p>
       * Should be set when the VideoState has the {@link VideoProfile#STATE_TX_ENABLED} or
       * {@link VideoProfile#STATE_RX_ENABLED} bits set to indicate that the connection cannot be
       * downgraded from a video call back to a VideoState of
       * {@link VideoProfile#STATE_AUDIO_ONLY}.
       * <p>
       * Intuitively, a call which can be downgraded to audio should also have local and remote
       * video
       * capabilities (see {@link #CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL} and
       * {@link #CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL}).
       */
      public static final int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO = 0x00800000;
  
      /**
       * When set for an external connection, indicates that this {@code Connection} can be pulled
       * from a remote device to the current device.
       * <p>
       * Should only be set on a {@code Connection} where {@link #PROPERTY_IS_EXTERNAL_CALL}
       * is set.
       */
      public static final int CAPABILITY_CAN_PULL_CALL = 0x01000000;
  
      /** Call supports the deflect feature. */
      public static final int CAPABILITY_SUPPORT_DEFLECT = 0x02000000;
  
      //**********************************************************************************************
      // Next CAPABILITY value: 0x04000000
      //**********************************************************************************************
  
      /**
       * Indicates that the current device callback number should be shown.
       *
       * @hide
       */
      public static final int PROPERTY_EMERGENCY_CALLBACK_MODE = 1<<0;
  
      /**
       * Whether the call is a generic conference, where we do not know the precise state of
       * participants in the conference (eg. on CDMA).
       *
       * @hide
       */
      public static final int PROPERTY_GENERIC_CONFERENCE = 1<<1;
  
      /**
       * Connection is using high definition audio.
       * @hide
       */
      public static final int PROPERTY_HIGH_DEF_AUDIO = 1<<2;
  
      /**
       * Connection is using WIFI.
       * @hide
       */
      public static final int PROPERTY_WIFI = 1<<3;
  
      /**
       * When set, indicates that the {@code Connection} does not actually exist locally for the
       * {@link ConnectionService}.
       * <p>
       * Consider, for example, a scenario where a user has two devices with the same phone number.
       * When a user places a call on one devices, the telephony stack can represent that call on the
       * other device by adding is to the {@link ConnectionService} with the
       * {@link #PROPERTY_IS_EXTERNAL_CALL} capability set.
       * <p>
       * An {@link ConnectionService} should not assume that all {@link InCallService}s will handle
       * external connections.  Only those {@link InCallService}s which have the
       * {@link TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS} metadata set to {@code true} in its
       * manifest will see external connections.
       */
      public static final int PROPERTY_IS_EXTERNAL_CALL = 1<<4;
  
      /**
       * Indicates that the connection has CDMA Enhanced Voice Privacy enabled.
       */
      public static final int PROPERTY_HAS_CDMA_VOICE_PRIVACY = 1<<5;
  
      /**
       * Indicates that the connection represents a downgraded IMS conference.
       * @hide
       */
      public static final int PROPERTY_IS_DOWNGRADED_CONFERENCE = 1<<6;
  
      /**
       * Set by the framework to indicate that the {@link Connection} originated from a self-managed
       * {@link ConnectionService}.
       * <p>
       * See {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.
       */
      public static final int PROPERTY_SELF_MANAGED = 1<<7;
  
      /**
       * Set by the framework to indicate that a connection has an active RTT session associated with
       * it.
       */
      public static final int PROPERTY_IS_RTT = 1 << 8;
  
      /**
       * Set by the framework to indicate that a connection is using assisted dialing.
       * @hide
       */
      public static final int PROPERTY_ASSISTED_DIALING_USED = 1 << 9;
  
      /**
       * Set by the framework to indicate that the network has identified a Connection as an emergency
       * call.
       * @hide
       */
      public static final int PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL = 1 << 10;
  
      /**
       * Set by the framework to indicate that a Conference or Connection is hosted by a device other
       * than the current one.  Used in scenarios where the conference originator is the remote device
       * and the current device is a participant of that conference.
       * @hide
       */
      public static final int PROPERTY_REMOTELY_HOSTED = 1 << 11;
  
      //**********************************************************************************************
      // Next PROPERTY value: 1<<12
      //**********************************************************************************************
  
      /**
       * Connection extra key used to store the last forwarded number associated with the current
       * connection.  Used to communicate to the user interface that the connection was forwarded via
       * the specified number.
       */
      public static final String EXTRA_LAST_FORWARDED_NUMBER =
              "android.telecom.extra.LAST_FORWARDED_NUMBER";
  
      /**
       * Connection extra key used to store a child number associated with the current connection.
       * Used to communicate to the user interface that the connection was received via
       * a child address (i.e. phone number) associated with the {@link PhoneAccount}'s primary
       * address.
       */
      public static final String EXTRA_CHILD_ADDRESS = "android.telecom.extra.CHILD_ADDRESS";
  
      /**
       * Connection extra key used to store the subject for an incoming call.  The user interface can
       * query this extra and display its contents for incoming calls.  Will only be used if the
       * {@link PhoneAccount} supports the capability {@link PhoneAccount#CAPABILITY_CALL_SUBJECT}.
       */
      public static final String EXTRA_CALL_SUBJECT = "android.telecom.extra.CALL_SUBJECT";
  
      /**
       * Boolean connection extra key set on a {@link Connection} in
       * {@link Connection#STATE_RINGING} state to indicate that answering the call will cause the
       * current active foreground call to be dropped.
       */
      public static final String EXTRA_ANSWERING_DROPS_FG_CALL =
              "android.telecom.extra.ANSWERING_DROPS_FG_CALL";
  
      /**
       * String connection extra key set on a {@link Connection} in {@link Connection#STATE_RINGING}
       * state to indicate the name of the third-party app which is responsible for the current
       * foreground call.
       * <p>
       * Used when {@link #EXTRA_ANSWERING_DROPS_FG_CALL} is true to ensure that the default Phone app
       * is able to inform the user that answering the new incoming call will cause a call owned by
       * another app to be dropped when the incoming call is answered.
       */
      public static final String EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME =
              "android.telecom.extra.ANSWERING_DROPS_FG_CALL_APP_NAME";
  
      /**
       * Boolean connection extra key on a {@link Connection} which indicates that adding an
       * additional call is disallowed.
       * @hide
       */
      public static final String EXTRA_DISABLE_ADD_CALL =
              "android.telecom.extra.DISABLE_ADD_CALL";
  
      /**
       * String connection extra key on a {@link Connection} or {@link Conference} which contains the
       * original Connection ID associated with the connection.  Used in
       * {@link RemoteConnectionService} to track the Connection ID which was originally assigned to a
       * connection/conference added via
       * {@link ConnectionService#addExistingConnection(PhoneAccountHandle, Connection)} and
       * {@link ConnectionService#addConference(Conference)} APIs.  This is important to pass to
       * Telecom for when it deals with RemoteConnections.  When the ConnectionManager wraps the
       * {@link RemoteConnection} and {@link RemoteConference} and adds it to Telecom, there needs to
       * be a way to ensure that we don't add the connection again as a duplicate.
       * <p>
       * For example, the TelephonyCS calls addExistingConnection for a Connection with ID
       * {@code TelephonyCS@1}.  The ConnectionManager learns of this via
       * {@link ConnectionService#onRemoteExistingConnectionAdded(RemoteConnection)}, and wraps this
       * in a new {@link Connection} which it adds to Telecom via
       * {@link ConnectionService#addExistingConnection(PhoneAccountHandle, Connection)}.  As part of
       * this process, the wrapped RemoteConnection gets assigned a new ID (e.g. {@code ConnMan@1}).
       * The TelephonyCS will ALSO try to add the existing connection to Telecom, except with the
       * ID it originally referred to the connection as.  Thus Telecom needs to know that the
       * Connection with ID {@code ConnMan@1} is really the same as {@code TelephonyCS@1}.
       * @hide
       */
      public static final String EXTRA_ORIGINAL_CONNECTION_ID =
              "android.telecom.extra.ORIGINAL_CONNECTION_ID";
  
      /**
       * Boolean connection extra key set on the extras passed to
       * {@link Connection#sendConnectionEvent} which indicates that audio is present
       * on the RTT call when the extra value is true.
       */
      public static final String EXTRA_IS_RTT_AUDIO_PRESENT =
              "android.telecom.extra.IS_RTT_AUDIO_PRESENT";
  
      /**
       * Connection event used to inform Telecom that it should play the on hold tone.  This is used
       * to play a tone when the peer puts the current call on hold.  Sent to Telecom via
       * {@link #sendConnectionEvent(String, Bundle)}.
       * @hide
       */
      public static final String EVENT_ON_HOLD_TONE_START =
              "android.telecom.event.ON_HOLD_TONE_START";
  
      /**
       * Connection event used to inform Telecom that it should stop the on hold tone.  This is used
       * to stop a tone when the peer puts the current call on hold.  Sent to Telecom via
       * {@link #sendConnectionEvent(String, Bundle)}.
       * @hide
       */
      public static final String EVENT_ON_HOLD_TONE_END =
              "android.telecom.event.ON_HOLD_TONE_END";
  
      /**
       * Connection event used to inform {@link InCallService}s when pulling of an external call has
       * failed.  The user interface should inform the user of the error.
       * <p>
       * Expected to be used by the {@link ConnectionService} when the {@link Call#pullExternalCall()}
       * API is called on a {@link Call} with the properties
       * {@link Call.Details#PROPERTY_IS_EXTERNAL_CALL} and
       * {@link Call.Details#CAPABILITY_CAN_PULL_CALL}, but the {@link ConnectionService} could not
       * pull the external call due to an error condition.
       * <p>
       * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
       * expected to be null when this connection event is used.
       */
      public static final String EVENT_CALL_PULL_FAILED = "android.telecom.event.CALL_PULL_FAILED";
  
      /**
       * Connection event used to inform {@link InCallService}s when the merging of two calls has
       * failed. The User Interface should use this message to inform the user of the error.
       * <p>
       * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
       * expected to be null when this connection event is used.
       */
      public static final String EVENT_CALL_MERGE_FAILED = "android.telecom.event.CALL_MERGE_FAILED";
  
      /**
       * Connection event used to inform Telecom when a hold operation on a call has failed.
       * Not intended for use by the UI at this time.
       * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
       * expected to be null when this connection event is used.
       * @hide
       */
      public static final String EVENT_CALL_HOLD_FAILED = "android.telecom.event.CALL_HOLD_FAILED";
  
      /**
       * Connection event used to inform {@link InCallService}s when the process of merging a
       * Connection into a conference has begun.
       * <p>
       * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
       * expected to be null when this connection event is used.
       * @hide
       */
      public static final String EVENT_MERGE_START = "android.telecom.event.MERGE_START";
  
      /**
       * Connection event used to inform {@link InCallService}s when the process of merging a
       * Connection into a conference has completed.
       * <p>
       * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
       * expected to be null when this connection event is used.
       * @hide
       */
      public static final String EVENT_MERGE_COMPLETE = "android.telecom.event.MERGE_COMPLETE";
  
      /**
       * Connection event used to inform {@link InCallService}s when a call has been put on hold by
       * the remote party.
       * <p>
       * This is different than the {@link Connection#STATE_HOLDING} state which indicates that the
       * call is being held locally on the device.  When a capable {@link ConnectionService} receives
       * signalling to indicate that the remote party has put the call on hold, it can send this
       * connection event.
       * @hide
       */
      public static final String EVENT_CALL_REMOTELY_HELD =
              "android.telecom.event.CALL_REMOTELY_HELD";
  
      /**
       * Connection event used to inform {@link InCallService}s when a call which was remotely held
       * (see {@link #EVENT_CALL_REMOTELY_HELD}) has been un-held by the remote party.
       * <p>
       * This is different than the {@link Connection#STATE_HOLDING} state which indicates that the
       * call is being held locally on the device.  When a capable {@link ConnectionService} receives
       * signalling to indicate that the remote party has taken the call off hold, it can send this
       * connection event.
       * @hide
       */
      public static final String EVENT_CALL_REMOTELY_UNHELD =
              "android.telecom.event.CALL_REMOTELY_UNHELD";
  
      /**
       * Connection event used to inform an {@link InCallService} which initiated a call handover via
       * {@link Call#EVENT_REQUEST_HANDOVER} that the handover from this {@link Connection} has
       * successfully completed.
       * @hide
       * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
       * APIs instead.
       */
      public static final String EVENT_HANDOVER_COMPLETE =
              "android.telecom.event.HANDOVER_COMPLETE";
  
      /**
       * Connection event used to inform an {@link InCallService} which initiated a call handover via
       * {@link Call#EVENT_REQUEST_HANDOVER} that the handover from this {@link Connection} has failed
       * to complete.
       * @hide
       * @deprecated Use {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} and its associated
       * APIs instead.
       */
      public static final String EVENT_HANDOVER_FAILED =
              "android.telecom.event.HANDOVER_FAILED";
  
      /**
       * String Connection extra key used to store SIP invite fields for an incoming call for IMS call
       */
      public static final String EXTRA_SIP_INVITE = "android.telecom.extra.SIP_INVITE";
  
      /**
       * Connection event used to inform an {@link InCallService} that the RTT audio indication
       * has changed.
       */
      public static final String EVENT_RTT_AUDIO_INDICATION_CHANGED =
              "android.telecom.event.RTT_AUDIO_INDICATION_CHANGED";
  
      // Flag controlling whether PII is emitted into the logs
      private static final boolean PII_DEBUG = Log.isLoggable(android.util.Log.DEBUG);
  
      /**
       * Whether the given capabilities support the specified capability.
       *
       * @param capabilities A capability bit field.
       * @param capability The capability to check capabilities for.
       * @return Whether the specified capability is supported.
       * @hide
       */
      public static boolean can(int capabilities, int capability) {
          return (capabilities & capability) == capability;
      }
  
      /**
       * Whether the capabilities of this {@code Connection} supports the specified capability.
       *
       * @param capability The capability to check capabilities for.
       * @return Whether the specified capability is supported.
       * @hide
       */
      public boolean can(int capability) {
          return can(mConnectionCapabilities, capability);
      }
  
      /**
       * Removes the specified capability from the set of capabilities of this {@code Connection}.
       *
       * @param capability The capability to remove from the set.
       * @hide
       */
      public void removeCapability(int capability) {
          mConnectionCapabilities &= ~capability;
      }
  
      /**
       * Adds the specified capability to the set of capabilities of this {@code Connection}.
       *
       * @param capability The capability to add to the set.
       * @hide
       */
      public void addCapability(int capability) {
          mConnectionCapabilities |= capability;
      }
  
      /**
       * Renders a set of capability bits ({@code CAPABILITY_*}) as a human readable string.
       *
       * @param capabilities A capability bit field.
       * @return A human readable string representation.
       */
      public static String capabilitiesToString(int capabilities) {
          return capabilitiesToStringInternal(capabilities, true /* isLong */);
      }
  
      /**
       * Renders a set of capability bits ({@code CAPABILITY_*}) as a *short* human readable
       * string.
       *
       * @param capabilities A capability bit field.
       * @return A human readable string representation.
       * @hide
       */
      public static String capabilitiesToStringShort(int capabilities) {
          return capabilitiesToStringInternal(capabilities, false /* isLong */);
      }
  
      private static String capabilitiesToStringInternal(int capabilities, boolean isLong) {
          StringBuilder builder = new StringBuilder();
          builder.append("[");
          if (isLong) {
              builder.append("Capabilities:");
          }
  
          if (can(capabilities, CAPABILITY_HOLD)) {
              builder.append(isLong ? " CAPABILITY_HOLD" : " hld");
          }
          if (can(capabilities, CAPABILITY_SUPPORT_HOLD)) {
              builder.append(isLong ? " CAPABILITY_SUPPORT_HOLD" : " sup_hld");
          }
          if (can(capabilities, CAPABILITY_MERGE_CONFERENCE)) {
              builder.append(isLong ? " CAPABILITY_MERGE_CONFERENCE" : " mrg_cnf");
          }
          if (can(capabilities, CAPABILITY_SWAP_CONFERENCE)) {
              builder.append(isLong ? " CAPABILITY_SWAP_CONFERENCE" : " swp_cnf");
          }
          if (can(capabilities, CAPABILITY_RESPOND_VIA_TEXT)) {
              builder.append(isLong ? " CAPABILITY_RESPOND_VIA_TEXT" : " txt");
          }
          if (can(capabilities, CAPABILITY_MUTE)) {
              builder.append(isLong ? " CAPABILITY_MUTE" : " mut");
          }
          if (can(capabilities, CAPABILITY_MANAGE_CONFERENCE)) {
              builder.append(isLong ? " CAPABILITY_MANAGE_CONFERENCE" : " mng_cnf");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_RX)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_RX" : " VTlrx");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_TX)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_TX" : " VTltx");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL" : " VTlbi");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_RX)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_RX" : " VTrrx");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_TX)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_TX" : " VTrtx");
          }
          if (can(capabilities, CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL)) {
              builder.append(isLong ? " CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL" : " VTrbi");
          }
          if (can(capabilities, CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO)) {
              builder.append(isLong ? " CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO" : " !v2a");
          }
          if (can(capabilities, CAPABILITY_SPEED_UP_MT_AUDIO)) {
              builder.append(isLong ? " CAPABILITY_SPEED_UP_MT_AUDIO" : " spd_aud");
          }
          if (can(capabilities, CAPABILITY_CAN_UPGRADE_TO_VIDEO)) {
              builder.append(isLong ? " CAPABILITY_CAN_UPGRADE_TO_VIDEO" : " a2v");
          }
          if (can(capabilities, CAPABILITY_CAN_PAUSE_VIDEO)) {
              builder.append(isLong ? " CAPABILITY_CAN_PAUSE_VIDEO" : " paus_VT");
          }
          if (can(capabilities, CAPABILITY_CONFERENCE_HAS_NO_CHILDREN)) {
              builder.append(isLong ? " CAPABILITY_SINGLE_PARTY_CONFERENCE" : " 1p_cnf");
          }
          if (can(capabilities, CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION)) {
              builder.append(isLong ? " CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION" : " rsp_by_con");
          }
          if (can(capabilities, CAPABILITY_CAN_PULL_CALL)) {
              builder.append(isLong ? " CAPABILITY_CAN_PULL_CALL" : " pull");
          }
          if (can(capabilities, CAPABILITY_SUPPORT_DEFLECT)) {
              builder.append(isLong ? " CAPABILITY_SUPPORT_DEFLECT" : " sup_def");
          }
  
          builder.append("]");
          return builder.toString();
      }
  
      /**
       * Renders a set of property bits ({@code PROPERTY_*}) as a human readable string.
       *
       * @param properties A property bit field.
       * @return A human readable string representation.
       */
      public static String propertiesToString(int properties) {
          return propertiesToStringInternal(properties, true /* isLong */);
      }
  
      /**
       * Renders a set of property bits ({@code PROPERTY_*}) as a *short* human readable string.
       *
       * @param properties A property bit field.
       * @return A human readable string representation.
       * @hide
       */
      public static String propertiesToStringShort(int properties) {
          return propertiesToStringInternal(properties, false /* isLong */);
      }
  
      private static String propertiesToStringInternal(int properties, boolean isLong) {
          StringBuilder builder = new StringBuilder();
          builder.append("[");
          if (isLong) {
              builder.append("Properties:");
          }
  
          if (can(properties, PROPERTY_SELF_MANAGED)) {
              builder.append(isLong ? " PROPERTY_SELF_MANAGED" : " self_mng");
          }
  
          if (can(properties, PROPERTY_EMERGENCY_CALLBACK_MODE)) {
              builder.append(isLong ? " PROPERTY_EMERGENCY_CALLBACK_MODE" : " ecbm");
          }
  
          if (can(properties, PROPERTY_HIGH_DEF_AUDIO)) {
              builder.append(isLong ? " PROPERTY_HIGH_DEF_AUDIO" : " HD");
          }
  
          if (can(properties, PROPERTY_WIFI)) {
              builder.append(isLong ? " PROPERTY_WIFI" : " wifi");
          }
  
          if (can(properties, PROPERTY_GENERIC_CONFERENCE)) {
              builder.append(isLong ? " PROPERTY_GENERIC_CONFERENCE" : " gen_conf");
          }
  
          if (can(properties, PROPERTY_IS_EXTERNAL_CALL)) {
              builder.append(isLong ? " PROPERTY_IS_EXTERNAL_CALL" : " xtrnl");
          }
  
          if (can(properties, PROPERTY_HAS_CDMA_VOICE_PRIVACY)) {
              builder.append(isLong ? " PROPERTY_HAS_CDMA_VOICE_PRIVACY" : " priv");
          }
  
          if (can(properties, PROPERTY_IS_RTT)) {
              builder.append(isLong ? " PROPERTY_IS_RTT" : " rtt");
          }
  
          if (can(properties, PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL)) {
              builder.append(isLong ? " PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL" : " ecall");
          }
  
          if (can(properties, PROPERTY_REMOTELY_HOSTED)) {
              builder.append(isLong ? " PROPERTY_REMOTELY_HOSTED" : " remote_hst");
          }
  
          builder.append("]");
          return builder.toString();
      }
  
      /** @hide */
      public abstract static class Listener {
          public void onStateChanged(Connection c, int state) {}
          public void onAddressChanged(Connection c, Uri newAddress, int presentation) {}
          public void onCallerDisplayNameChanged(
                  Connection c, String callerDisplayName, int presentation) {}
          public void onVideoStateChanged(Connection c, int videoState) {}
          public void onDisconnected(Connection c, DisconnectCause disconnectCause) {}
          public void onPostDialWait(Connection c, String remaining) {}
          public void onPostDialChar(Connection c, char nextChar) {}
          public void onRingbackRequested(Connection c, boolean ringback) {}
          public void onDestroyed(Connection c) {}
          public void onConnectionCapabilitiesChanged(Connection c, int capabilities) {}
          public void onConnectionPropertiesChanged(Connection c, int properties) {}
          public void onSupportedAudioRoutesChanged(Connection c, int supportedAudioRoutes) {}
          public void onVideoProviderChanged(
                  Connection c, VideoProvider videoProvider) {}
          public void onAudioModeIsVoipChanged(Connection c, boolean isVoip) {}
          public void onStatusHintsChanged(Connection c, StatusHints statusHints) {}
          public void onConferenceablesChanged(
                  Connection c, List<Conferenceable> conferenceables) {}
          public void onConferenceChanged(Connection c, Conference conference) {}
          /** @hide */
          public void onConferenceParticipantsChanged(Connection c,
                  List<ConferenceParticipant> participants) {}
          public void onConferenceStarted() {}
          public void onConferenceMergeFailed(Connection c) {}
          public void onExtrasChanged(Connection c, Bundle extras) {}
          public void onExtrasRemoved(Connection c, List<String> keys) {}
          public void onConnectionEvent(Connection c, String event, Bundle extras) {}
          /** @hide */
          public void onConferenceSupportedChanged(Connection c, boolean isConferenceSupported) {}
          public void onAudioRouteChanged(Connection c, int audioRoute, String bluetoothAddress) {}
          public void onRttInitiationSuccess(Connection c) {}
          public void onRttInitiationFailure(Connection c, int reason) {}
          public void onRttSessionRemotelyTerminated(Connection c) {}
          public void onRemoteRttRequest(Connection c) {}
          /** @hide */
          public void onPhoneAccountChanged(Connection c, PhoneAccountHandle pHandle) {}
          public void onConnectionTimeReset(Connection c) {}
      }
  
      /**
       * Provides methods to read and write RTT data to/from the in-call app.
       */
      public static final class RttTextStream {
          private static final int READ_BUFFER_SIZE = 1000;
          private final InputStreamReader mPipeFromInCall;
          private final OutputStreamWriter mPipeToInCall;
          private final ParcelFileDescriptor mFdFromInCall;
          private final ParcelFileDescriptor mFdToInCall;
  
          private final FileInputStream mFromInCallFileInputStream;
          private char[] mReadBuffer = new char[READ_BUFFER_SIZE];
  
          /**
           * @hide
           */
          public RttTextStream(ParcelFileDescriptor toInCall, ParcelFileDescriptor fromInCall) {
              mFdFromInCall = fromInCall;
              mFdToInCall = toInCall;
              mFromInCallFileInputStream = new FileInputStream(fromInCall.getFileDescriptor());
  
              // Wrap the FileInputStream in a Channel so that it's interruptible.
              mPipeFromInCall = new InputStreamReader(
                      Channels.newInputStream(Channels.newChannel(mFromInCallFileInputStream)));
              mPipeToInCall = new OutputStreamWriter(
                      new FileOutputStream(toInCall.getFileDescriptor()));
          }
  
          /**
           * Writes the string {@param input} into the text stream to the UI for this RTT call. Since
           * RTT transmits text in real-time, this method should be called as often as text snippets
           * are received from the remote user, even if it is only one character.
           * <p>
           * This method is not thread-safe -- calling it from multiple threads simultaneously may
           * lead to interleaved text.
           *
           * @param input The message to send to the in-call app.
           */
          public void write(String input) throws IOException {
              mPipeToInCall.write(input);
              mPipeToInCall.flush();
          }
  
  
          /**
           * Reads a string from the in-call app, blocking if there is no data available. Returns
           * {@code null} if the RTT conversation has been terminated and there is no further data
           * to read.
           * <p>
           * This method is not thread-safe -- calling it from multiple threads simultaneously may
           * lead to interleaved text.
           *
           * @return A string containing text entered by the user, or {@code null} if the
           * conversation has been terminated or if there was an error while reading.
           */
          public String read() throws IOException {
              int numRead = mPipeFromInCall.read(mReadBuffer, 0, READ_BUFFER_SIZE);
              if (numRead < 0) {
                  return null;
              }
              return new String(mReadBuffer, 0, numRead);
          }
  
          /**
           * Non-blocking version of {@link #read()}. Returns {@code null} if there is nothing to
           * be read.
           *
           * @return A string containing text entered by the user, or {@code null} if the user has
           * not entered any new text yet.
           */
          public String readImmediately() throws IOException {
              if (mFromInCallFileInputStream.available() > 0) {
                  return read();
              } else {
                  return null;
              }
          }
  
          /** @hide */
          public ParcelFileDescriptor getFdFromInCall() {
              return mFdFromInCall;
          }
  
          /** @hide */
          public ParcelFileDescriptor getFdToInCall() {
              return mFdToInCall;
          }
      }
  
      /**
       * Provides constants to represent the results of responses to session modify requests sent via
       * {@link Call#sendRttRequest()}
       */
      public static final class RttModifyStatus {
          private RttModifyStatus() {}
          /**
           * Session modify request was successful.
           */
          public static final int SESSION_MODIFY_REQUEST_SUCCESS = 1;
  
          /**
           * Session modify request failed.
           */
          public static final int SESSION_MODIFY_REQUEST_FAIL = 2;
  
          /**
           * Session modify request ignored due to invalid parameters.
           */
          public static final int SESSION_MODIFY_REQUEST_INVALID = 3;
  
          /**
           * Session modify request timed out.
           */
          public static final int SESSION_MODIFY_REQUEST_TIMED_OUT = 4;
  
          /**
           * Session modify request rejected by remote user.
           */
          public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE = 5;
      }
  
      /**
       * Provides a means of controlling the video session associated with a {@link Connection}.
       * <p>
       * Implementations create a custom subclass of {@link VideoProvider} and the
       * {@link ConnectionService} creates an instance sets it on the {@link Connection} using
       * {@link Connection#setVideoProvider(VideoProvider)}.  Any connection which supports video
       * should set the {@link VideoProvider}.
       * <p>
       * The {@link VideoProvider} serves two primary purposes: it provides a means for Telecom and
       * {@link InCallService} implementations to issue requests related to the video session;
       * it provides a means for the {@link ConnectionService} to report events and information
       * related to the video session to Telecom and the {@link InCallService} implementations.
       * <p>
       * {@link InCallService} implementations interact with the {@link VideoProvider} via
       * {@link android.telecom.InCallService.VideoCall}.
       */
      public static abstract class VideoProvider {
          /**
           * Video is not being received (no protocol pause was issued).
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_RX_PAUSE = 1;
  
          /**
           * Video reception has resumed after a {@link #SESSION_EVENT_RX_PAUSE}.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_RX_RESUME = 2;
  
          /**
           * Video transmission has begun. This occurs after a negotiated start of video transmission
           * when the underlying protocol has actually begun transmitting video to the remote party.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_TX_START = 3;
  
          /**
           * Video transmission has stopped. This occurs after a negotiated stop of video transmission
           * when the underlying protocol has actually stopped transmitting video to the remote party.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_TX_STOP = 4;
  
          /**
           * A camera failure has occurred for the selected camera.  The {@link VideoProvider} can use
           * this as a cue to inform the user the camera is not available.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_CAMERA_FAILURE = 5;
  
          /**
           * Issued after {@link #SESSION_EVENT_CAMERA_FAILURE} when the camera is once again ready
           * for operation.  The {@link VideoProvider} can use this as a cue to inform the user that
           * the camera has become available again.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_CAMERA_READY = 6;
  
          /**
           * Session event raised by Telecom when
           * {@link android.telecom.InCallService.VideoCall#setCamera(String)} is called and the
           * caller does not have the necessary {@link android.Manifest.permission#CAMERA} permission.
           * @see #handleCallSessionEvent(int)
           */
          public static final int SESSION_EVENT_CAMERA_PERMISSION_ERROR = 7;
  
          /**
           * Session modify request was successful.
           * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
           */
          public static final int SESSION_MODIFY_REQUEST_SUCCESS = 1;
  
          /**
           * Session modify request failed.
           * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
           */
          public static final int SESSION_MODIFY_REQUEST_FAIL = 2;
  
          /**
           * Session modify request ignored due to invalid parameters.
           * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
           */
          public static final int SESSION_MODIFY_REQUEST_INVALID = 3;
  
          /**
           * Session modify request timed out.
           * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
           */
          public static final int SESSION_MODIFY_REQUEST_TIMED_OUT = 4;
  
          /**
           * Session modify request rejected by remote user.
           * @see #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)
           */
          public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE = 5;
  
          private static final int MSG_ADD_VIDEO_CALLBACK = 1;
          private static final int MSG_SET_CAMERA = 2;
          private static final int MSG_SET_PREVIEW_SURFACE = 3;
          private static final int MSG_SET_DISPLAY_SURFACE = 4;
          private static final int MSG_SET_DEVICE_ORIENTATION = 5;
          private static final int MSG_SET_ZOOM = 6;
          private static final int MSG_SEND_SESSION_MODIFY_REQUEST = 7;
          private static final int MSG_SEND_SESSION_MODIFY_RESPONSE = 8;
          private static final int MSG_REQUEST_CAMERA_CAPABILITIES = 9;
          private static final int MSG_REQUEST_CONNECTION_DATA_USAGE = 10;
          private static final int MSG_SET_PAUSE_IMAGE = 11;
          private static final int MSG_REMOVE_VIDEO_CALLBACK = 12;
  
          private static final String SESSION_EVENT_RX_PAUSE_STR = "RX_PAUSE";
          private static final String SESSION_EVENT_RX_RESUME_STR = "RX_RESUME";
          private static final String SESSION_EVENT_TX_START_STR = "TX_START";
          private static final String SESSION_EVENT_TX_STOP_STR = "TX_STOP";
          private static final String SESSION_EVENT_CAMERA_FAILURE_STR = "CAMERA_FAIL";
          private static final String SESSION_EVENT_CAMERA_READY_STR = "CAMERA_READY";
          private static final String SESSION_EVENT_CAMERA_PERMISSION_ERROR_STR =
                  "CAMERA_PERMISSION_ERROR";
          private static final String SESSION_EVENT_UNKNOWN_STR = "UNKNOWN";
  
          private VideoProvider.VideoProviderHandler mMessageHandler;
          private final VideoProvider.VideoProviderBinder mBinder;
  
          /**
           * Stores a list of the video callbacks, keyed by IBinder.
           *
           * ConcurrentHashMap constructor params: 8 is initial table size, 0.9f is
           * load factor before resizing, 1 means we only expect a single thread to
           * access the map so make only a single shard
           */
          private ConcurrentHashMap<IBinder, IVideoCallback> mVideoCallbacks =
                  new ConcurrentHashMap<IBinder, IVideoCallback>(8, 0.9f, 1);
  
          /**
           * Default handler used to consolidate binder method calls onto a single thread.
           */
          private final class VideoProviderHandler extends Handler {
              public VideoProviderHandler() {
                  super();
              }
  
              public VideoProviderHandler(Looper looper) {
                  super(looper);
              }
  
              @Override
              public void handleMessage(Message msg) {
                  switch (msg.what) {
                      case MSG_ADD_VIDEO_CALLBACK: {
                          IBinder binder = (IBinder) msg.obj;
                          IVideoCallback callback = IVideoCallback.Stub
                                  .asInterface((IBinder) msg.obj);
                          if (callback == null) {
                              Log.w(this, "addVideoProvider - skipped; callback is null.");
                              break;
                          }
  
                          if (mVideoCallbacks.containsKey(binder)) {
                              Log.i(this, "addVideoProvider - skipped; already present.");
                              break;
                          }
                          mVideoCallbacks.put(binder, callback);
                          break;
                      }
                      case MSG_REMOVE_VIDEO_CALLBACK: {
                          IBinder binder = (IBinder) msg.obj;
                          IVideoCallback callback = IVideoCallback.Stub
                                  .asInterface((IBinder) msg.obj);
                          if (!mVideoCallbacks.containsKey(binder)) {
                              Log.i(this, "removeVideoProvider - skipped; not present.");
                              break;
                          }
                          mVideoCallbacks.remove(binder);
                          break;
                      }
                      case MSG_SET_CAMERA:
                      {
                          SomeArgs args = (SomeArgs) msg.obj;
                          try {
                              onSetCamera((String) args.arg1);
                              onSetCamera((String) args.arg1, (String) args.arg2, args.argi1,
                                      args.argi2, args.argi3);
                          } finally {
                              args.recycle();
                          }
                      }
                      break;
                      case MSG_SET_PREVIEW_SURFACE:
                          onSetPreviewSurface((Surface) msg.obj);
                          break;
                      case MSG_SET_DISPLAY_SURFACE:
                          onSetDisplaySurface((Surface) msg.obj);
                          break;
                      case MSG_SET_DEVICE_ORIENTATION:
                          onSetDeviceOrientation(msg.arg1);
                          break;
                      case MSG_SET_ZOOM:
                          onSetZoom((Float) msg.obj);
                          break;
                      case MSG_SEND_SESSION_MODIFY_REQUEST: {
                          SomeArgs args = (SomeArgs) msg.obj;
                          try {
                              onSendSessionModifyRequest((VideoProfile) args.arg1,
                                      (VideoProfile) args.arg2);
                          } finally {
                              args.recycle();
                          }
                          break;
                      }
                      case MSG_SEND_SESSION_MODIFY_RESPONSE:
                          onSendSessionModifyResponse((VideoProfile) msg.obj);
                          break;
                      case MSG_REQUEST_CAMERA_CAPABILITIES:
                          onRequestCameraCapabilities();
                          break;
                      case MSG_REQUEST_CONNECTION_DATA_USAGE:
                          onRequestConnectionDataUsage();
                          break;
                      case MSG_SET_PAUSE_IMAGE:
                          onSetPauseImage((Uri) msg.obj);
                          break;
                      default:
                          break;
                  }
              }
          }
  
          /**
           * IVideoProvider stub implementation.
           */
          private final class VideoProviderBinder extends IVideoProvider.Stub {
              public void addVideoCallback(IBinder videoCallbackBinder) {
                  mMessageHandler.obtainMessage(
                          MSG_ADD_VIDEO_CALLBACK, videoCallbackBinder).sendToTarget();
              }
  
              public void removeVideoCallback(IBinder videoCallbackBinder) {
                  mMessageHandler.obtainMessage(
                          MSG_REMOVE_VIDEO_CALLBACK, videoCallbackBinder).sendToTarget();
              }
  
              public void setCamera(String cameraId, String callingPackageName,
                                    int targetSdkVersion) {
  
                  SomeArgs args = SomeArgs.obtain();
                  args.arg1 = cameraId;
                  // Propagate the calling package; originally determined in
                  // android.telecom.InCallService.VideoCall#setCamera(String) from the calling
                  // process.
                  args.arg2 = callingPackageName;
                  // Pass along the uid and pid of the calling app; this gets lost when we put the
                  // message onto the handler.  These are required for Telecom to perform a permission
                  // check to see if the calling app is able to use the camera.
                  args.argi1 = Binder.getCallingUid();
                  args.argi2 = Binder.getCallingPid();
                  // Pass along the target SDK version of the calling InCallService.  This is used to
                  // maintain backwards compatibility of the API for older callers.
                  args.argi3 = targetSdkVersion;
                  mMessageHandler.obtainMessage(MSG_SET_CAMERA, args).sendToTarget();
              }
  
              public void setPreviewSurface(Surface surface) {
                  mMessageHandler.obtainMessage(MSG_SET_PREVIEW_SURFACE, surface).sendToTarget();
              }
  
              public void setDisplaySurface(Surface surface) {
                  mMessageHandler.obtainMessage(MSG_SET_DISPLAY_SURFACE, surface).sendToTarget();
              }
  
              public void setDeviceOrientation(int rotation) {
                  mMessageHandler.obtainMessage(
                          MSG_SET_DEVICE_ORIENTATION, rotation, 0).sendToTarget();
              }
  
              public void setZoom(float value) {
                  mMessageHandler.obtainMessage(MSG_SET_ZOOM, value).sendToTarget();
              }
  
              public void sendSessionModifyRequest(VideoProfile fromProfile, VideoProfile toProfile) {
                  SomeArgs args = SomeArgs.obtain();
                  args.arg1 = fromProfile;
                  args.arg2 = toProfile;
                  mMessageHandler.obtainMessage(MSG_SEND_SESSION_MODIFY_REQUEST, args).sendToTarget();
              }
  
              public void sendSessionModifyResponse(VideoProfile responseProfile) {
                  mMessageHandler.obtainMessage(
                          MSG_SEND_SESSION_MODIFY_RESPONSE, responseProfile).sendToTarget();
              }
  
              public void requestCameraCapabilities() {
                  mMessageHandler.obtainMessage(MSG_REQUEST_CAMERA_CAPABILITIES).sendToTarget();
              }
  
              public void requestCallDataUsage() {
                  mMessageHandler.obtainMessage(MSG_REQUEST_CONNECTION_DATA_USAGE).sendToTarget();
              }
  
              public void setPauseImage(Uri uri) {
                  mMessageHandler.obtainMessage(MSG_SET_PAUSE_IMAGE, uri).sendToTarget();
              }
          }
  
          public VideoProvider() {
              mBinder = new VideoProvider.VideoProviderBinder();
              mMessageHandler = new VideoProvider.VideoProviderHandler(Looper.getMainLooper());
          }
  
          /**
           * Creates an instance of the {@link VideoProvider}, specifying the looper to use.
           *
           * @param looper The looper.
           * @hide
           */
          @UnsupportedAppUsage
          public VideoProvider(Looper looper) {
              mBinder = new VideoProvider.VideoProviderBinder();
              mMessageHandler = new VideoProvider.VideoProviderHandler(looper);
          }
  
          /**
           * Returns binder object which can be used across IPC methods.
           * @hide
           */
          public final IVideoProvider getInterface() {
              return mBinder;
          }
  
          /**
           * Sets the camera to be used for the outgoing video.
           * <p>
           * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
           * camera via
           * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setCamera(String)}.
           *
           * @param cameraId The id of the camera (use ids as reported by
           * {@link CameraManager#getCameraIdList()}).
           */
          public abstract void onSetCamera(String cameraId);
  
          /**
           * Sets the camera to be used for the outgoing video.
           * <p>
           * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
           * camera via
           * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
           * <p>
           * This prototype is used internally to ensure that the calling package name, UID and PID
           * are sent to Telecom so that can perform a camera permission check on the caller.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setCamera(String)}.
           *
           * @param cameraId The id of the camera (use ids as reported by
           * {@link CameraManager#getCameraIdList()}).
           * @param callingPackageName The AppOpps package name of the caller.
           * @param callingUid The UID of the caller.
           * @param callingPid The PID of the caller.
           * @param targetSdkVersion The target SDK version of the caller.
           * @hide
           */
          public void onSetCamera(String cameraId, String callingPackageName, int callingUid,
                  int callingPid, int targetSdkVersion) {}
  
          /**
           * Sets the surface to be used for displaying a preview of what the user's camera is
           * currently capturing.  When video transmission is enabled, this is the video signal which
           * is sent to the remote device.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setPreviewSurface(Surface)}.
           *
           * @param surface The {@link Surface}.
           */
          public abstract void onSetPreviewSurface(Surface surface);
  
          /**
           * Sets the surface to be used for displaying the video received from the remote device.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setDisplaySurface(Surface)}.
           *
           * @param surface The {@link Surface}.
           */
          public abstract void onSetDisplaySurface(Surface surface);
  
          /**
           * Sets the device orientation, in degrees.  Assumes that a standard portrait orientation of
           * the device is 0 degrees.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setDeviceOrientation(int)}.
           *
           * @param rotation The device orientation, in degrees.
           */
          public abstract void onSetDeviceOrientation(int rotation);
  
          /**
           * Sets camera zoom ratio.
           * <p>
           * Sent from the {@link InCallService} via {@link InCallService.VideoCall#setZoom(float)}.
           *
           * @param value The camera zoom ratio.
           */
          public abstract void onSetZoom(float value);
  
          /**
           * Issues a request to modify the properties of the current video session.
           * <p>
           * Example scenarios include: requesting an audio-only call to be upgraded to a
           * bi-directional video call, turning on or off the user's camera, sending a pause signal
           * when the {@link InCallService} is no longer the foreground application.
           * <p>
           * If the {@link VideoProvider} determines a request to be invalid, it should call
           * {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)} to report the
           * invalid request back to the {@link InCallService}.
           * <p>
           * Where a request requires confirmation from the user of the peer device, the
           * {@link VideoProvider} must communicate the request to the peer device and handle the
           * user's response.  {@link #receiveSessionModifyResponse(int, VideoProfile, VideoProfile)}
           * is used to inform the {@link InCallService} of the result of the request.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#sendSessionModifyRequest(VideoProfile)}.
           *
           * @param fromProfile The video profile prior to the request.
           * @param toProfile The video profile with the requested changes made.
           */
          public abstract void onSendSessionModifyRequest(VideoProfile fromProfile,
                  VideoProfile toProfile);
  
          /**
           * Provides a response to a request to change the current video session properties.
           * <p>
           * For example, if the peer requests and upgrade from an audio-only call to a bi-directional
           * video call, could decline the request and keep the call as audio-only.
           * In such a scenario, the {@code responseProfile} would have a video state of
           * {@link VideoProfile#STATE_AUDIO_ONLY}.  If the user had decided to accept the request,
           * the video state would be {@link VideoProfile#STATE_BIDIRECTIONAL}.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#sendSessionModifyResponse(VideoProfile)} in response to
           * a {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)}
           * callback.
           *
           * @param responseProfile The response video profile.
           */
          public abstract void onSendSessionModifyResponse(VideoProfile responseProfile);
  
          /**
           * Issues a request to the {@link VideoProvider} to retrieve the camera capabilities.
           * <p>
           * The {@link VideoProvider} should respond by communicating the capabilities of the chosen
           * camera via
           * {@link VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities)}.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#requestCameraCapabilities()}.
           */
          public abstract void onRequestCameraCapabilities();
  
          /**
           * Issues a request to the {@link VideoProvider} to retrieve the current data usage for the
           * video component of the current {@link Connection}.
           * <p>
           * The {@link VideoProvider} should respond by communicating current data usage, in bytes,
           * via {@link VideoProvider#setCallDataUsage(long)}.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#requestCallDataUsage()}.
           */
          public abstract void onRequestConnectionDataUsage();
  
          /**
           * Provides the {@link VideoProvider} with the {@link Uri} of an image to be displayed to
           * the peer device when the video signal is paused.
           * <p>
           * Sent from the {@link InCallService} via
           * {@link InCallService.VideoCall#setPauseImage(Uri)}.
           *
           * @param uri URI of image to display.
           */
          public abstract void onSetPauseImage(Uri uri);
  
          /**
           * Used to inform listening {@link InCallService} implementations when the
           * {@link VideoProvider} receives a session modification request.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile)},
           *
           * @param videoProfile The requested video profile.
           * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
           */
          public void receiveSessionModifyRequest(VideoProfile videoProfile) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.receiveSessionModifyRequest(videoProfile);
                      } catch (RemoteException ignored) {
                          Log.w(this, "receiveSessionModifyRequest callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the
           * {@link VideoProvider} receives a response to a session modification request.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onSessionModifyResponseReceived(int,
           * VideoProfile, VideoProfile)}.
           *
           * @param status Status of the session modify request.  Valid values are
           *               {@link VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
           *               {@link VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
           *               {@link VideoProvider#SESSION_MODIFY_REQUEST_INVALID},
           *               {@link VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT},
           *               {@link VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE}
           * @param requestedProfile The original request which was sent to the peer device.
           * @param responseProfile The actual profile changes agreed to by the peer device.
           * @see #onSendSessionModifyRequest(VideoProfile, VideoProfile)
           */
          public void receiveSessionModifyResponse(int status,
                  VideoProfile requestedProfile, VideoProfile responseProfile) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.receiveSessionModifyResponse(status, requestedProfile,
                                  responseProfile);
                      } catch (RemoteException ignored) {
                          Log.w(this, "receiveSessionModifyResponse callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the
           * {@link VideoProvider} reports a call session event.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onCallSessionEvent(int)}.
           *
           * @param event The event.  Valid values are: {@link VideoProvider#SESSION_EVENT_RX_PAUSE},
           *      {@link VideoProvider#SESSION_EVENT_RX_RESUME},
           *      {@link VideoProvider#SESSION_EVENT_TX_START},
           *      {@link VideoProvider#SESSION_EVENT_TX_STOP},
           *      {@link VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
           *      {@link VideoProvider#SESSION_EVENT_CAMERA_READY},
           *      {@link VideoProvider#SESSION_EVENT_CAMERA_FAILURE}.
           */
          public void handleCallSessionEvent(int event) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.handleCallSessionEvent(event);
                      } catch (RemoteException ignored) {
                          Log.w(this, "handleCallSessionEvent callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the dimensions of the
           * peer's video have changed.
           * <p>
           * This could occur if, for example, the peer rotates their device, changing the aspect
           * ratio of the video, or if the user switches between the back and front cameras.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onPeerDimensionsChanged(int, int)}.
           *
           * @param width  The updated peer video width.
           * @param height The updated peer video height.
           */
          public void changePeerDimensions(int width, int height) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.changePeerDimensions(width, height);
                      } catch (RemoteException ignored) {
                          Log.w(this, "changePeerDimensions callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the data usage of the
           * video associated with the current {@link Connection} has changed.
           * <p>
           * This could be in response to a preview request via
           * {@link #onRequestConnectionDataUsage()}, or as a periodic update by the
           * {@link VideoProvider}.  Where periodic updates of data usage are provided, they should be
           * provided at most for every 1 MB of data transferred and no more than once every 10 sec.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onCallDataUsageChanged(long)}.
           *
           * @param dataUsage The updated data usage (in bytes).  Reported as the cumulative bytes
           *                  used since the start of the call.
           */
          public void setCallDataUsage(long dataUsage) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.changeCallDataUsage(dataUsage);
                      } catch (RemoteException ignored) {
                          Log.w(this, "setCallDataUsage callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * @see #setCallDataUsage(long)
           *
           * @param dataUsage The updated data usage (in byes).
           * @deprecated - Use {@link #setCallDataUsage(long)} instead.
           * @hide
           */
          public void changeCallDataUsage(long dataUsage) {
              setCallDataUsage(dataUsage);
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the capabilities of
           * the current camera have changed.
           * <p>
           * The {@link VideoProvider} should call this in response to
           * {@link VideoProvider#onRequestCameraCapabilities()}, or when the current camera is
           * changed via {@link VideoProvider#onSetCamera(String)}.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onCameraCapabilitiesChanged(
           * VideoProfile.CameraCapabilities)}.
           *
           * @param cameraCapabilities The new camera capabilities.
           */
          public void changeCameraCapabilities(VideoProfile.CameraCapabilities cameraCapabilities) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.changeCameraCapabilities(cameraCapabilities);
                      } catch (RemoteException ignored) {
                          Log.w(this, "changeCameraCapabilities callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Used to inform listening {@link InCallService} implementations when the video quality
           * of the call has changed.
           * <p>
           * Received by the {@link InCallService} via
           * {@link InCallService.VideoCall.Callback#onVideoQualityChanged(int)}.
           *
           * @param videoQuality The updated video quality.  Valid values:
           *      {@link VideoProfile#QUALITY_HIGH},
           *      {@link VideoProfile#QUALITY_MEDIUM},
           *      {@link VideoProfile#QUALITY_LOW},
           *      {@link VideoProfile#QUALITY_DEFAULT}.
           */
          public void changeVideoQuality(int videoQuality) {
              if (mVideoCallbacks != null) {
                  for (IVideoCallback callback : mVideoCallbacks.values()) {
                      try {
                          callback.changeVideoQuality(videoQuality);
                      } catch (RemoteException ignored) {
                          Log.w(this, "changeVideoQuality callback failed", ignored);
                      }
                  }
              }
          }
  
          /**
           * Returns a string representation of a call session event.
           *
           * @param event A call session event passed to {@link #handleCallSessionEvent(int)}.
           * @return String representation of the call session event.
           * @hide
           */
          public static String sessionEventToString(int event) {
              switch (event) {
                  case SESSION_EVENT_CAMERA_FAILURE:
                      return SESSION_EVENT_CAMERA_FAILURE_STR;
                  case SESSION_EVENT_CAMERA_READY:
                      return SESSION_EVENT_CAMERA_READY_STR;
                  case SESSION_EVENT_RX_PAUSE:
                      return SESSION_EVENT_RX_PAUSE_STR;
                  case SESSION_EVENT_RX_RESUME:
                      return SESSION_EVENT_RX_RESUME_STR;
                  case SESSION_EVENT_TX_START:
                      return SESSION_EVENT_TX_START_STR;
                  case SESSION_EVENT_TX_STOP:
                      return SESSION_EVENT_TX_STOP_STR;
                  case SESSION_EVENT_CAMERA_PERMISSION_ERROR:
                      return SESSION_EVENT_CAMERA_PERMISSION_ERROR_STR;
                  default:
                      return SESSION_EVENT_UNKNOWN_STR + " " + event;
              }
          }
      }
  
      private final Listener mConnectionDeathListener = new Listener() {
          @Override
          public void onDestroyed(Connection c) {
              if (mConferenceables.remove(c)) {
                  fireOnConferenceableConnectionsChanged();
              }
          }
      };
  
      private final Conference.Listener mConferenceDeathListener = new Conference.Listener() {
          @Override
          public void onDestroyed(Conference c) {
              if (mConferenceables.remove(c)) {
                  fireOnConferenceableConnectionsChanged();
              }
          }
      };
  
      /**
       * ConcurrentHashMap constructor params: 8 is initial table size, 0.9f is
       * load factor before resizing, 1 means we only expect a single thread to
       * access the map so make only a single shard
       */
      private final Set<Listener> mListeners = Collections.newSetFromMap(
              new ConcurrentHashMap<Listener, Boolean>(8, 0.9f, 1));
      private final List<Conferenceable> mConferenceables = new ArrayList<>();
      private final List<Conferenceable> mUnmodifiableConferenceables =
              Collections.unmodifiableList(mConferenceables);
  
      // The internal telecom call ID associated with this connection.
      private String mTelecomCallId;
      // The PhoneAccountHandle associated with this connection.
      private PhoneAccountHandle mPhoneAccountHandle;
      private int mState = STATE_NEW;
      private CallAudioState mCallAudioState;
      private Uri mAddress;
      private int mAddressPresentation;
      private String mCallerDisplayName;
      private int mCallerDisplayNamePresentation;
      private boolean mRingbackRequested = false;
      private int mConnectionCapabilities;
      private int mConnectionProperties;
      private int mSupportedAudioRoutes = CallAudioState.ROUTE_ALL;
      private VideoProvider mVideoProvider;
      private boolean mAudioModeIsVoip;
      private long mConnectTimeMillis = Conference.CONNECT_TIME_NOT_SPECIFIED;
      private long mConnectElapsedTimeMillis = Conference.CONNECT_TIME_NOT_SPECIFIED;
      private StatusHints mStatusHints;
      private int mVideoState;
      private DisconnectCause mDisconnectCause;
      private Conference mConference;
      private ConnectionService mConnectionService;
      private Bundle mExtras;
      private final Object mExtrasLock = new Object();
      /**
       * The direction of the connection; used where an existing connection is created and we need to
       * communicate to Telecom whether its incoming or outgoing.
       */
      private @Call.Details.CallDirection int mCallDirection = Call.Details.DIRECTION_UNKNOWN;
  
      /**
       * Tracks the key set for the extras bundle provided on the last invocation of
       * {@link #setExtras(Bundle)}.  Used so that on subsequent invocations we can remove any extras
       * keys which were set previously but are no longer present in the replacement Bundle.
       */
      private Set<String> mPreviousExtraKeys;
  
      /**
       * Create a new Connection.
       */
      public Connection() {}
  
      /**
       * Returns the Telecom internal call ID associated with this connection.  Should only be used
       * for debugging and tracing purposes.
       *
       * @return The Telecom call ID.
       * @hide
       */
      public final String getTelecomCallId() {
          return mTelecomCallId;
      }
  
      /**
       * @return The address (e.g., phone number) to which this Connection is currently communicating.
       */
      public final Uri getAddress() {
          return mAddress;
      }
  
      /**
       * @return The presentation requirements for the address.
       *         See {@link TelecomManager} for valid values.
       */
      public final int getAddressPresentation() {
          return mAddressPresentation;
      }
  
      /**
       * @return The caller display name (CNAP).
       */
      public final String getCallerDisplayName() {
          return mCallerDisplayName;
      }
  
      /**
       * @return The presentation requirements for the handle.
       *         See {@link TelecomManager} for valid values.
       */
      public final int getCallerDisplayNamePresentation() {
          return mCallerDisplayNamePresentation;
      }
  
      /**
       * @return The state of this Connection.
       */
      public final int getState() {
          return mState;
      }
  
      /**
       * Returns the video state of the connection.
       * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
       * {@link VideoProfile#STATE_BIDIRECTIONAL},
       * {@link VideoProfile#STATE_TX_ENABLED},
       * {@link VideoProfile#STATE_RX_ENABLED}.
       *
       * @return The video state of the connection.
       * @hide
       */
      public final int getVideoState() {
          return mVideoState;
      }
  
      /**
       * @return The audio state of the connection, describing how its audio is currently
       *         being routed by the system. This is {@code null} if this Connection
       *         does not directly know about its audio state.
       * @deprecated Use {@link #getCallAudioState()} instead.
       * @hide
       */
      @SystemApi
      @Deprecated
      public final AudioState getAudioState() {
          if (mCallAudioState == null) {
            return null;
          }
          return new AudioState(mCallAudioState);
      }
  
      /**
       * @return The audio state of the connection, describing how its audio is currently
       *         being routed by the system. This is {@code null} if this Connection
       *         does not directly know about its audio state.
       */
      public final CallAudioState getCallAudioState() {
          return mCallAudioState;
      }
  
      /**
       * @return The conference that this connection is a part of.  Null if it is not part of any
       *         conference.
       */
      public final Conference getConference() {
          return mConference;
      }
  
      /**
       * Returns whether this connection is requesting that the system play a ringback tone
       * on its behalf.
       */
      public final boolean isRingbackRequested() {
          return mRingbackRequested;
      }
  
      /**
       * @return True if the connection's audio mode is VOIP.
       */
      public final boolean getAudioModeIsVoip() {
          return mAudioModeIsVoip;
      }
  
      /**
       * Retrieves the connection start time of the {@code Connnection}, if specified.  A value of
       * {@link Conference#CONNECT_TIME_NOT_SPECIFIED} indicates that Telecom should determine the
       * start time of the conference.
       *
       * @return The time at which the {@code Connnection} was connected.
       *
       * @hide
       */
      public final long getConnectTimeMillis() {
          return mConnectTimeMillis;
      }
  
      /**
       * Retrieves the connection start time of the {@link Connection}, if specified.  A value of
       * {@link Conference#CONNECT_TIME_NOT_SPECIFIED} indicates that Telecom should determine the
       * start time of the conference.
       *
       * Based on the value of {@link SystemClock#elapsedRealtime()}, which ensures that wall-clock
       * changes do not impact the call duration.
       *
       * @return The time at which the {@link Connection} was connected.
       *
       * @hide
       */
      public final long getConnectElapsedTimeMillis() {
          return mConnectElapsedTimeMillis;
      }
  
      /**
       * Returns RIL voice radio technology used for current connection.
       *
       * @return the RIL voice radio technology used for current connection,
       *         see {@code RIL_RADIO_TECHNOLOGY_*} in {@link android.telephony.ServiceState}.
       *
       * @hide
       */
      public final @ServiceState.RilRadioTechnology int getCallRadioTech() {
          int voiceNetworkType = TelephonyManager.NETWORK_TYPE_UNKNOWN;
          Bundle extras = getExtras();
          if (extras != null) {
              voiceNetworkType = extras.getInt(TelecomManager.EXTRA_CALL_NETWORK_TYPE,
                      TelephonyManager.NETWORK_TYPE_UNKNOWN);
          }
          return ServiceState.networkTypeToRilRadioTechnology(voiceNetworkType);
      }
  
      /**
       * @return The status hints for this connection.
       */
      public final StatusHints getStatusHints() {
          return mStatusHints;
      }
  
      /**
       * Returns the extras associated with this connection.
       * <p>
       * Extras should be updated using {@link #putExtras(Bundle)}.
       * <p>
       * Telecom or an {@link InCallService} can also update the extras via
       * {@link android.telecom.Call#putExtras(Bundle)}, and
       * {@link Call#removeExtras(List)}.
       * <p>
       * The connection is notified of changes to the extras made by Telecom or an
       * {@link InCallService} by {@link #onExtrasChanged(Bundle)}.
       *
       * @return The extras associated with this connection.
       */
      public final Bundle getExtras() {
          Bundle extras = null;
          synchronized (mExtrasLock) {
              if (mExtras != null) {
                  extras = new Bundle(mExtras);
              }
          }
          return extras;
      }
  
      /**
       * Assign a listener to be notified of state changes.
       *
       * @param l A listener.
       * @return This Connection.
       *
       * @hide
       */
      public final Connection addConnectionListener(Listener l) {
          mListeners.add(l);
          return this;
      }
  
      /**
       * Remove a previously assigned listener that was being notified of state changes.
       *
       * @param l A Listener.
       * @return This Connection.
       *
       * @hide
       */
      public final Connection removeConnectionListener(Listener l) {
          if (l != null) {
              mListeners.remove(l);
          }
          return this;
      }
  
      /**
       * @return The {@link DisconnectCause} for this connection.
       */
      public final DisconnectCause getDisconnectCause() {
          return mDisconnectCause;
      }
  
      /**
       * Sets the telecom call ID associated with this Connection.  The Telecom Call ID should be used
       * ONLY for debugging purposes.
       *
       * @param callId The telecom call ID.
       * @hide
       */
      public void setTelecomCallId(String callId) {
          mTelecomCallId = callId;
      }
  
      /**
       * Inform this Connection that the state of its audio output has been changed externally.
       *
       * @param state The new audio state.
       * @hide
       */
      final void setCallAudioState(CallAudioState state) {
          checkImmutable();
          Log.d(this, "setAudioState %s", state);
          mCallAudioState = state;
          onAudioStateChanged(getAudioState());
          onCallAudioStateChanged(state);
      }
  
      /**
       * @param state An integer value of a {@code STATE_*} constant.
       * @return A string representation of the value.
       */
      public static String stateToString(int state) {
          switch (state) {
              case STATE_INITIALIZING:
                  return "INITIALIZING";
              case STATE_NEW:
                  return "NEW";
              case STATE_RINGING:
                  return "RINGING";
              case STATE_DIALING:
                  return "DIALING";
              case STATE_PULLING_CALL:
                  return "PULLING_CALL";
              case STATE_ACTIVE:
                  return "ACTIVE";
              case STATE_HOLDING:
                  return "HOLDING";
              case STATE_DISCONNECTED:
                  return "DISCONNECTED";
              default:
                  Log.wtf(Connection.class, "Unknown state %d", state);
                  return "UNKNOWN";
          }
      }
  
      /**
       * Returns the connection's capabilities, as a bit mask of the {@code CAPABILITY_*} constants.
       */
      public final int getConnectionCapabilities() {
          return mConnectionCapabilities;
      }
  
      /**
       * Returns the connection's properties, as a bit mask of the {@code PROPERTY_*} constants.
       */
      public final int getConnectionProperties() {
          return mConnectionProperties;
      }
  
      /**
       * Returns the connection's supported audio routes.
       *
       * @hide
       */
      public final int getSupportedAudioRoutes() {
          return mSupportedAudioRoutes;
      }
  
      /**
       * Sets the value of the {@link #getAddress()} property.
       *
       * @param address The new address.
       * @param presentation The presentation requirements for the address.
       *        See {@link TelecomManager} for valid values.
       */
      public final void setAddress(Uri address, int presentation) {
          checkImmutable();
          Log.d(this, "setAddress %s", address);
          mAddress = address;
          mAddressPresentation = presentation;
          for (Listener l : mListeners) {
              l.onAddressChanged(this, address, presentation);
          }
      }
  
      /**
       * Sets the caller display name (CNAP).
       *
       * @param callerDisplayName The new display name.
       * @param presentation The presentation requirements for the handle.
       *        See {@link TelecomManager} for valid values.
       */
      public final void setCallerDisplayName(String callerDisplayName, int presentation) {
          checkImmutable();
          Log.d(this, "setCallerDisplayName %s", callerDisplayName);
          mCallerDisplayName = callerDisplayName;
          mCallerDisplayNamePresentation = presentation;
          for (Listener l : mListeners) {
              l.onCallerDisplayNameChanged(this, callerDisplayName, presentation);
          }
      }
  
      /**
       * Set the video state for the connection.
       * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
       * {@link VideoProfile#STATE_BIDIRECTIONAL},
       * {@link VideoProfile#STATE_TX_ENABLED},
       * {@link VideoProfile#STATE_RX_ENABLED}.
       *
       * @param videoState The new video state.
       */
      public final void setVideoState(int videoState) {
          checkImmutable();
          Log.d(this, "setVideoState %d", videoState);
          mVideoState = videoState;
          for (Listener l : mListeners) {
              l.onVideoStateChanged(this, mVideoState);
          }
      }
  
      /**
       * Sets state to active (e.g., an ongoing connection where two or more parties can actively
       * communicate).
       */
      public final void setActive() {
          checkImmutable();
          setRingbackRequested(false);
          setState(STATE_ACTIVE);
      }
  
      /**
       * Sets state to ringing (e.g., an inbound ringing connection).
       */
      public final void setRinging() {
          checkImmutable();
          setState(STATE_RINGING);
      }
  
      /**
       * Sets state to initializing (this Connection is not yet ready to be used).
       */
      public final void setInitializing() {
          checkImmutable();
          setState(STATE_INITIALIZING);
      }
  
      /**
       * Sets state to initialized (the Connection has been set up and is now ready to be used).
       */
      public final void setInitialized() {
          checkImmutable();
          setState(STATE_NEW);
      }
  
      /**
       * Sets state to dialing (e.g., dialing an outbound connection).
       */
      public final void setDialing() {
          checkImmutable();
          setState(STATE_DIALING);
      }
  
      /**
       * Sets state to pulling (e.g. the connection is being pulled to the local device from another
       * device).  Only applicable for {@link Connection}s with
       * {@link Connection#PROPERTY_IS_EXTERNAL_CALL} and {@link Connection#CAPABILITY_CAN_PULL_CALL}.
       */
      public final void setPulling() {
          checkImmutable();
          setState(STATE_PULLING_CALL);
      }
  
      /**
       * Sets state to be on hold.
       */
      public final void setOnHold() {
          checkImmutable();
          setState(STATE_HOLDING);
      }
  
      /**
       * Sets the video connection provider.
       * @param videoProvider The video provider.
       */
      public final void setVideoProvider(VideoProvider videoProvider) {
          checkImmutable();
          mVideoProvider = videoProvider;
          for (Listener l : mListeners) {
              l.onVideoProviderChanged(this, videoProvider);
          }
      }
  
      public final VideoProvider getVideoProvider() {
          return mVideoProvider;
      }
  
      /**
       * Sets state to disconnected.
       *
       * @param disconnectCause The reason for the disconnection, as specified by
       *         {@link DisconnectCause}.
       */
      public final void setDisconnected(DisconnectCause disconnectCause) {
          checkImmutable();
          mDisconnectCause = disconnectCause;
          setState(STATE_DISCONNECTED);
          Log.d(this, "Disconnected with cause %s", disconnectCause);
          for (Listener l : mListeners) {
              l.onDisconnected(this, disconnectCause);
          }
      }
  
      /**
       * Informs listeners that this {@code Connection} is in a post-dial wait state. This is done
       * when (a) the {@code Connection} is issuing a DTMF sequence; (b) it has encountered a "wait"
       * character; and (c) it wishes to inform the In-Call app that it is waiting for the end-user
       * to send an {@link #onPostDialContinue(boolean)} signal.
       *
       * @param remaining The DTMF character sequence remaining to be emitted once the
       *         {@link #onPostDialContinue(boolean)} is received, including any "wait" characters
       *         that remaining sequence may contain.
       */
      public final void setPostDialWait(String remaining) {
          checkImmutable();
          for (Listener l : mListeners) {
              l.onPostDialWait(this, remaining);
          }
      }
  
      /**
       * Informs listeners that this {@code Connection} has processed a character in the post-dial
       * started state. This is done when (a) the {@code Connection} is issuing a DTMF sequence;
       * and (b) it wishes to signal Telecom to play the corresponding DTMF tone locally.
       *
       * @param nextChar The DTMF character that was just processed by the {@code Connection}.
       */
      public final void setNextPostDialChar(char nextChar) {
          checkImmutable();
          for (Listener l : mListeners) {
              l.onPostDialChar(this, nextChar);
          }
      }
  
      /**
       * Requests that the framework play a ringback tone. This is to be invoked by implementations
       * that do not play a ringback tone themselves in the connection's audio stream.
       *
       * @param ringback Whether the ringback tone is to be played.
       */
      public final void setRingbackRequested(boolean ringback) {
          checkImmutable();
          if (mRingbackRequested != ringback) {
              mRingbackRequested = ringback;
              for (Listener l : mListeners) {
                  l.onRingbackRequested(this, ringback);
              }
          }
      }
  
      /**
       * Sets the connection's capabilities as a bit mask of the {@code CAPABILITY_*} constants.
       *
       * @param connectionCapabilities The new connection capabilities.
       */
      public final void setConnectionCapabilities(int connectionCapabilities) {
          checkImmutable();
          if (mConnectionCapabilities != connectionCapabilities) {
              mConnectionCapabilities = connectionCapabilities;
              for (Listener l : mListeners) {
                  l.onConnectionCapabilitiesChanged(this, mConnectionCapabilities);
              }
          }
      }
  
      /**
       * Sets the connection's properties as a bit mask of the {@code PROPERTY_*} constants.
       *
       * @param connectionProperties The new connection properties.
       */
      public final void setConnectionProperties(int connectionProperties) {
          checkImmutable();
          if (mConnectionProperties != connectionProperties) {
              mConnectionProperties = connectionProperties;
              for (Listener l : mListeners) {
                  l.onConnectionPropertiesChanged(this, mConnectionProperties);
              }
          }
      }
  
      /**
       * Sets the supported audio routes.
       *
       * @param supportedAudioRoutes the supported audio routes as a bitmask.
       *                             See {@link CallAudioState}
       * @hide
       */
      public final void setSupportedAudioRoutes(int supportedAudioRoutes) {
          if ((supportedAudioRoutes
                  & (CallAudioState.ROUTE_EARPIECE | CallAudioState.ROUTE_SPEAKER)) == 0) {
              throw new IllegalArgumentException(
                      "supported audio routes must include either speaker or earpiece");
          }
  
          if (mSupportedAudioRoutes != supportedAudioRoutes) {
              mSupportedAudioRoutes = supportedAudioRoutes;
              for (Listener l : mListeners) {
                  l.onSupportedAudioRoutesChanged(this, mSupportedAudioRoutes);
              }
          }
      }
  
      /**
       * Tears down the Connection object.
       */
      public final void destroy() {
          for (Listener l : mListeners) {
              l.onDestroyed(this);
          }
      }
  
      /**
       * Requests that the framework use VOIP audio mode for this connection.
       *
       * @param isVoip True if the audio mode is VOIP.
       */
      public final void setAudioModeIsVoip(boolean isVoip) {
          checkImmutable();
          mAudioModeIsVoip = isVoip;
          for (Listener l : mListeners) {
              l.onAudioModeIsVoipChanged(this, isVoip);
          }
      }
  
      /**
       * Sets the time at which a call became active on this Connection. This is set only
       * when a conference call becomes active on this connection.
       *
       * @param connectTimeMillis The connection time, in milliseconds.  Should be set using a value
       *                          obtained from {@link System#currentTimeMillis()}.
       *
       * @hide
       */
      public final void setConnectTimeMillis(long connectTimeMillis) {
          mConnectTimeMillis = connectTimeMillis;
      }
  
      /**
       * Sets the time at which a call became active on this Connection. This is set only
       * when a conference call becomes active on this connection.
       *
       * @param connectElapsedTimeMillis The connection time, in milliseconds.  Stored in the format
       *                              {@link SystemClock#elapsedRealtime()}.
       *
       * @hide
       */
      public final void setConnectionStartElapsedRealTime(long connectElapsedTimeMillis) {
          mConnectElapsedTimeMillis = connectElapsedTimeMillis;
      }
  
      /**
       * Sets RIL voice radio technology used for current connection.
       *
       * @param vrat the RIL Voice Radio Technology used for current connection,
       *             see {@code RIL_RADIO_TECHNOLOGY_*} in {@link android.telephony.ServiceState}.
       *
       * @hide
       */
      public final void setCallRadioTech(@ServiceState.RilRadioTechnology int vrat) {
          putExtra(TelecomManager.EXTRA_CALL_NETWORK_TYPE,
                  ServiceState.rilRadioTechnologyToNetworkType(vrat));
          // Propagates the call radio technology to its parent {@link android.telecom.Conference}
          // This action only covers non-IMS CS conference calls.
          // For IMS PS call conference call, it can be updated via its host connection
          // {@link #Listener.onExtrasChanged} event.
          if (getConference() != null) {
              getConference().setCallRadioTech(vrat);
          }
      }
  
      /**
       * Sets the label and icon status to display in the in-call UI.
       *
       * @param statusHints The status label and icon to set.
       */
      public final void setStatusHints(StatusHints statusHints) {
          checkImmutable();
          mStatusHints = statusHints;
          for (Listener l : mListeners) {
              l.onStatusHintsChanged(this, statusHints);
          }
      }
  
      /**
       * Sets the connections with which this connection can be conferenced.
       *
       * @param conferenceableConnections The set of connections this connection can conference with.
       */
      public final void setConferenceableConnections(List<Connection> conferenceableConnections) {
          checkImmutable();
          clearConferenceableList();
          for (Connection c : conferenceableConnections) {
              // If statement checks for duplicates in input. It makes it N^2 but we're dealing with a
              // small amount of items here.
              if (!mConferenceables.contains(c)) {
                  c.addConnectionListener(mConnectionDeathListener);
                  mConferenceables.add(c);
              }
          }
          fireOnConferenceableConnectionsChanged();
      }
  
      /**
       * Similar to {@link #setConferenceableConnections(java.util.List)}, sets a list of connections
       * or conferences with which this connection can be conferenced.
       *
       * @param conferenceables The conferenceables.
       */
      public final void setConferenceables(List<Conferenceable> conferenceables) {
          clearConferenceableList();
          for (Conferenceable c : conferenceables) {
              // If statement checks for duplicates in input. It makes it N^2 but we're dealing with a
              // small amount of items here.
              if (!mConferenceables.contains(c)) {
                  if (c instanceof Connection) {
                      Connection connection = (Connection) c;
                      connection.addConnectionListener(mConnectionDeathListener);
                  } else if (c instanceof Conference) {
                      Conference conference = (Conference) c;
                      conference.addListener(mConferenceDeathListener);
                  }
                  mConferenceables.add(c);
              }
          }
          fireOnConferenceableConnectionsChanged();
      }
  
      /**
       * @hide
       * Resets the cdma connection time.
       */
      public final void resetConnectionTime() {
          for (Listener l : mListeners) {
              l.onConnectionTimeReset(this);
          }
      }
  
      /**
       * Returns the connections or conferences with which this connection can be conferenced.
       */
      public final List<Conferenceable> getConferenceables() {
          return mUnmodifiableConferenceables;
      }
  
      /**
       * @hide
       */
      public final void setConnectionService(ConnectionService connectionService) {
          checkImmutable();
          if (mConnectionService != null) {
              Log.e(this, new Exception(), "Trying to set ConnectionService on a connection " +
                      "which is already associated with another ConnectionService.");
          } else {
              mConnectionService = connectionService;
          }
      }
  
      /**
       * @hide
       */
      public final void unsetConnectionService(ConnectionService connectionService) {
          if (mConnectionService != connectionService) {
              Log.e(this, new Exception(), "Trying to remove ConnectionService from a Connection " +
                      "that does not belong to the ConnectionService.");
          } else {
              mConnectionService = null;
          }
      }
  
      /**
       * @hide
       */
      public final ConnectionService getConnectionService() {
          return mConnectionService;
      }
  
      /**
       * Sets the conference that this connection is a part of. This will fail if the connection is
       * already part of a conference. {@link #resetConference} to un-set the conference first.
       *
       * @param conference The conference.
       * @return {@code true} if the conference was successfully set.
       * @hide
       */
      public final boolean setConference(Conference conference) {
          checkImmutable();
          // We check to see if it is already part of another conference.
          if (mConference == null) {
              mConference = conference;
              if (mConnectionService != null && mConnectionService.containsConference(conference)) {
                  fireConferenceChanged();
              }
              return true;
          }
          return false;
      }
  
      /**
       * Resets the conference that this connection is a part of.
       * @hide
       */
      public final void resetConference() {
          if (mConference != null) {
              Log.d(this, "Conference reset");
              mConference = null;
              fireConferenceChanged();
          }
      }
  
      /**
       * Set some extras that can be associated with this {@code Connection}.
       * <p>
       * New or existing keys are replaced in the {@code Connection} extras.  Keys which are no longer
       * in the new extras, but were present the last time {@code setExtras} was called are removed.
       * <p>
       * Alternatively you may use the {@link #putExtras(Bundle)}, and
       * {@link #removeExtras(String...)} methods to modify the extras.
       * <p>
       * No assumptions should be made as to how an In-Call UI or service will handle these extras.
       * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
       *
       * @param extras The extras associated with this {@code Connection}.
       */
      public final void setExtras(@Nullable Bundle extras) {
          checkImmutable();
  
          // Add/replace any new or changed extras values.
          putExtras(extras);
  
          // If we have used "setExtras" in the past, compare the key set from the last invocation to
          // the current one and remove any keys that went away.
          if (mPreviousExtraKeys != null) {
              List<String> toRemove = new ArrayList<String>();
              for (String oldKey : mPreviousExtraKeys) {
                  if (extras == null || !extras.containsKey(oldKey)) {
                      toRemove.add(oldKey);
                  }
              }
              if (!toRemove.isEmpty()) {
                  removeExtras(toRemove);
              }
          }
  
          // Track the keys the last time set called setExtras.  This way, the next time setExtras is
          // called we can see if the caller has removed any extras values.
          if (mPreviousExtraKeys == null) {
              mPreviousExtraKeys = new ArraySet<String>();
          }
          mPreviousExtraKeys.clear();
          if (extras != null) {
              mPreviousExtraKeys.addAll(extras.keySet());
          }
      }
  
      /**
       * Adds some extras to this {@code Connection}.  Existing keys are replaced and new ones are
       * added.
       * <p>
       * No assumptions should be made as to how an In-Call UI or service will handle these extras.
       * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
       *
       * @param extras The extras to add.
       */
      public final void putExtras(@NonNull Bundle extras) {
          checkImmutable();
          if (extras == null) {
              return;
          }
          // Creating a duplicate bundle so we don't have to synchronize on mExtrasLock while calling
          // the listeners.
          Bundle listenerExtras;
          synchronized (mExtrasLock) {
              if (mExtras == null) {
                  mExtras = new Bundle();
              }
              mExtras.putAll(extras);
              listenerExtras = new Bundle(mExtras);
          }
          for (Listener l : mListeners) {
              // Create a new clone of the extras for each listener so that they don't clobber
              // each other
              l.onExtrasChanged(this, new Bundle(listenerExtras));
          }
      }
  
      /**
       * Adds a boolean extra to this {@code Connection}.
       *
       * @param key The extra key.
       * @param value The value.
       * @hide
       */
      public final void putExtra(String key, boolean value) {
          Bundle newExtras = new Bundle();
          newExtras.putBoolean(key, value);
          putExtras(newExtras);
      }
  
      /**
       * Adds an integer extra to this {@code Connection}.
       *
       * @param key The extra key.
       * @param value The value.
       * @hide
       */
      public final void putExtra(String key, int value) {
          Bundle newExtras = new Bundle();
          newExtras.putInt(key, value);
          putExtras(newExtras);
      }
  
      /**
       * Adds a string extra to this {@code Connection}.
       *
       * @param key The extra key.
       * @param value The value.
       * @hide
       */
      public final void putExtra(String key, String value) {
          Bundle newExtras = new Bundle();
          newExtras.putString(key, value);
          putExtras(newExtras);
      }
  
      /**
       * Removes extras from this {@code Connection}.
       *
       * @param keys The keys of the extras to remove.
       */
      public final void removeExtras(List<String> keys) {
          synchronized (mExtrasLock) {
              if (mExtras != null) {
                  for (String key : keys) {
                      mExtras.remove(key);
                  }
              }
          }
          List<String> unmodifiableKeys = Collections.unmodifiableList(keys);
          for (Listener l : mListeners) {
              l.onExtrasRemoved(this, unmodifiableKeys);
          }
      }
  
      /**
       * Removes extras from this {@code Connection}.
       *
       * @param keys The keys of the extras to remove.
       */
      public final void removeExtras(String ... keys) {
          removeExtras(Arrays.asList(keys));
      }
  
      /**
       * Sets the audio route (speaker, bluetooth, etc...).  When this request is honored, there will
       * be change to the {@link #getCallAudioState()}.
       * <p>
       * Used by self-managed {@link ConnectionService}s which wish to change the audio route for a
       * self-managed {@link Connection} (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.)
       * <p>
       * See also {@link InCallService#setAudioRoute(int)}.
       *
       * @param route The audio route to use (one of {@link CallAudioState#ROUTE_BLUETOOTH},
       *              {@link CallAudioState#ROUTE_EARPIECE}, {@link CallAudioState#ROUTE_SPEAKER}, or
       *              {@link CallAudioState#ROUTE_WIRED_HEADSET}).
       */
      public final void setAudioRoute(int route) {
          for (Listener l : mListeners) {
              l.onAudioRouteChanged(this, route, null);
          }
      }
  
      /**
       * Request audio routing to a specific bluetooth device. Calling this method may result in
       * the device routing audio to a different bluetooth device than the one specified if the
       * bluetooth stack is unable to route audio to the requested device.
       * A list of available devices can be obtained via
       * {@link CallAudioState#getSupportedBluetoothDevices()}
       *
       * <p>
       * Used by self-managed {@link ConnectionService}s which wish to use bluetooth audio for a
       * self-managed {@link Connection} (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}.)
       * <p>
       * See also {@link InCallService#requestBluetoothAudio(BluetoothDevice)}
       * @param bluetoothDevice The bluetooth device to connect to.
       */
      public void requestBluetoothAudio(@NonNull BluetoothDevice bluetoothDevice) {
          for (Listener l : mListeners) {
              l.onAudioRouteChanged(this, CallAudioState.ROUTE_BLUETOOTH,
                      bluetoothDevice.getAddress());
          }
      }
  
      /**
       * Informs listeners that a previously requested RTT session via
       * {@link ConnectionRequest#isRequestingRtt()} or
       * {@link #onStartRtt(RttTextStream)} has succeeded.
       */
      public final void sendRttInitiationSuccess() {
          mListeners.forEach((l) -> l.onRttInitiationSuccess(Connection.this));
      }
  
      /**
       * Informs listeners that a previously requested RTT session via
       * {@link ConnectionRequest#isRequestingRtt()} or {@link #onStartRtt(RttTextStream)}
       * has failed.
       * @param reason One of the reason codes defined in {@link RttModifyStatus}, with the
       *               exception of {@link RttModifyStatus#SESSION_MODIFY_REQUEST_SUCCESS}.
       */
      public final void sendRttInitiationFailure(int reason) {
          mListeners.forEach((l) -> l.onRttInitiationFailure(Connection.this, reason));
      }
  
      /**
       * Informs listeners that a currently active RTT session has been terminated by the remote
       * side of the coll.
       */
      public final void sendRttSessionRemotelyTerminated() {
          mListeners.forEach((l) -> l.onRttSessionRemotelyTerminated(Connection.this));
      }
  
      /**
       * Informs listeners that the remote side of the call has requested an upgrade to include an
       * RTT session in the call.
       */
      public final void sendRemoteRttRequest() {
          mListeners.forEach((l) -> l.onRemoteRttRequest(Connection.this));
      }
  
      /**
       * Notifies this Connection that the {@link #getAudioState()} property has a new value.
       *
       * @param state The new connection audio state.
       * @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.
       * @hide
       */
      @SystemApi
      @Deprecated
      public void onAudioStateChanged(AudioState state) {}
  
      /**
       * Notifies this Connection that the {@link #getCallAudioState()} property has a new value.
       *
       * @param state The new connection audio state.
       */
      public void onCallAudioStateChanged(CallAudioState state) {}
  
      /**
       * Notifies this Connection of an internal state change. This method is called after the
       * state is changed.
       *
       * @param state The new state, one of the {@code STATE_*} constants.
       */
      public void onStateChanged(int state) {}
  
      /**
       * Notifies this Connection of a request to play a DTMF tone.
       *
       * @param c A DTMF character.
       */
      public void onPlayDtmfTone(char c) {}
  
      /**
       * Notifies this Connection of a request to stop any currently playing DTMF tones.
       */
      public void onStopDtmfTone() {}
  
      /**
       * Notifies this Connection of a request to disconnect.
       */
      public void onDisconnect() {}
  
      /**
       * Notifies this Connection of a request to disconnect a participant of the conference managed
       * by the connection.
       *
       * @param endpoint the {@link Uri} of the participant to disconnect.
       * @hide
       */
      public void onDisconnectConferenceParticipant(Uri endpoint) {}
  
      /**
       * Notifies this Connection of a request to separate from its parent conference.
       */
      public void onSeparate() {}
  
      /**
       * Notifies this Connection of a request to abort.
       */
      public void onAbort() {}
  
      /**
       * Notifies this Connection of a request to hold.
       */
      public void onHold() {}
  
      /**
       * Notifies this Connection of a request to exit a hold state.
       */
      public void onUnhold() {}
  
      /**
       * Notifies this Connection, which is in {@link #STATE_RINGING}, of
       * a request to accept.
       * <p>
       * For managed {@link ConnectionService}s, this will be called when the user answers a call via
       * the default dialer's {@link InCallService}.
       * <p>
       * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
       * Telecom framework may request that the call is answered in the following circumstances:
       * <ul>
       *     <li>The user chooses to answer an incoming call via a Bluetooth device.</li>
       *     <li>A car mode {@link InCallService} is in use which has declared
       *     {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest.  Such an
       *     {@link InCallService} will be able to see calls from self-managed
       *     {@link ConnectionService}s, and will be able to display an incoming call UI on their
       *     behalf.</li>
       * </ul>
       * @param videoState The video state in which to answer the connection.
       */
      public void onAnswer(int videoState) {}
  
      /**
       * Notifies this Connection, which is in {@link #STATE_RINGING}, of
       * a request to accept.
       * <p>
       * For managed {@link ConnectionService}s, this will be called when the user answers a call via
       * the default dialer's {@link InCallService}.
       * <p>
       * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
       * Telecom framework may request that the call is answered in the following circumstances:
       * <ul>
       *     <li>The user chooses to answer an incoming call via a Bluetooth device.</li>
       *     <li>A car mode {@link InCallService} is in use which has declared
       *     {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest.  Such an
       *     {@link InCallService} will be able to see calls from self-managed
       *     {@link ConnectionService}s, and will be able to display an incoming call UI on their
       *     behalf.</li>
       * </ul>
       */
      public void onAnswer() {
          onAnswer(VideoProfile.STATE_AUDIO_ONLY);
      }
  
      /**
       * Notifies this Connection, which is in {@link #STATE_RINGING}, of
       * a request to deflect.
       */
      public void onDeflect(Uri address) {}
  
      /**
       * Notifies this Connection, which is in {@link #STATE_RINGING}, of
       * a request to reject.
       * <p>
       * For managed {@link ConnectionService}s, this will be called when the user rejects a call via
       * the default dialer's {@link InCallService}.
       * <p>
       * Although a self-managed {@link ConnectionService} provides its own incoming call UI, the
       * Telecom framework may request that the call is rejected in the following circumstances:
       * <ul>
       *     <li>The user chooses to reject an incoming call via a Bluetooth device.</li>
       *     <li>A car mode {@link InCallService} is in use which has declared
       *     {@link TelecomManager#METADATA_INCLUDE_SELF_MANAGED_CALLS} in its manifest.  Such an
       *     {@link InCallService} will be able to see calls from self-managed
       *     {@link ConnectionService}s, and will be able to display an incoming call UI on their
       *     behalf.</li>
       * </ul>
       */
      public void onReject() {}
  
      /**
       * Notifies this Connection, which is in {@link #STATE_RINGING}, of
       * a request to reject with a message.
       */
      public void onReject(String replyMessage) {}
  
      /**
       * Notifies this Connection of a request to silence the ringer.
       * <p>
       * The ringer may be silenced by any of the following methods:
       * <ul>
       *     <li>{@link TelecomManager#silenceRinger()}</li>
       *     <li>The user presses the volume-down button while a call is ringing.</li>
       * </ul>
       * <p>
       * Self-managed {@link ConnectionService} implementations should override this method in their
       * {@link Connection} implementation and implement logic to silence their app's ringtone.  If
       * your app set the ringtone as part of the incoming call {@link Notification} (see
       * {@link #onShowIncomingCallUi()}), it should re-post the notification now, except call
       * {@link android.app.Notification.Builder#setOnlyAlertOnce(boolean)} with {@code true}.  This
       * will ensure the ringtone sound associated with your {@link android.app.NotificationChannel}
       * stops playing.
       */
      public void onSilence() {}
  
      /**
       * Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.
       */
      public void onPostDialContinue(boolean proceed) {}
  
      /**
       * Notifies this Connection of a request to pull an external call to the local device.
       * <p>
       * The {@link InCallService} issues a request to pull an external call to the local device via
       * {@link Call#pullExternalCall()}.
       * <p>
       * For a Connection to be pulled, both the {@link Connection#CAPABILITY_CAN_PULL_CALL}
       * capability and {@link Connection#PROPERTY_IS_EXTERNAL_CALL} property bits must be set.
       * <p>
       * For more information on external calls, see {@link Connection#PROPERTY_IS_EXTERNAL_CALL}.
       */
      public void onPullExternalCall() {}
  
      /**
       * Notifies this Connection of a {@link Call} event initiated from an {@link InCallService}.
       * <p>
       * The {@link InCallService} issues a Call event via {@link Call#sendCallEvent(String, Bundle)}.
       * <p>
       * Where possible, the Connection should make an attempt to handle {@link Call} events which
       * are part of the {@code android.telecom.*} namespace.  The Connection should ignore any events
       * it does not wish to handle.  Unexpected events should be handled gracefully, as it is
       * possible that a {@link InCallService} has defined its own Call events which a Connection is
       * not aware of.
       * <p>
       * See also {@link Call#sendCallEvent(String, Bundle)}.
       *
       * @param event The call event.
       * @param extras Extras associated with the call event.
       */
      public void onCallEvent(String event, Bundle extras) {}
  
      /**
       * Notifies this {@link Connection} that a handover has completed.
       * <p>
       * A handover is initiated with {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int,
       * Bundle)} on the initiating side of the handover, and
       * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}.
       */
      public void onHandoverComplete() {}
  
      /**
       * Notifies this {@link Connection} of a change to the extras made outside the
       * {@link ConnectionService}.
       * <p>
       * These extras changes can originate from Telecom itself, or from an {@link InCallService} via
       * the {@link android.telecom.Call#putExtras(Bundle)} and
       * {@link Call#removeExtras(List)}.
       *
       * @param extras The new extras bundle.
       */
      public void onExtrasChanged(Bundle extras) {}
  
      /**
       * Notifies this {@link Connection} that its {@link ConnectionService} is responsible for
       * displaying its incoming call user interface for the {@link Connection}.
       * <p>
       * Will only be called for incoming calls added via a self-managed {@link ConnectionService}
       * (see {@link PhoneAccount#CAPABILITY_SELF_MANAGED}), where the {@link ConnectionService}
       * should show its own incoming call user interface.
       * <p>
       * Where there are ongoing calls in other self-managed {@link ConnectionService}s, or in a
       * regular {@link ConnectionService}, and it is not possible to hold these other calls, the
       * Telecom framework will display its own incoming call user interface to allow the user to
       * choose whether to answer the new incoming call and disconnect other ongoing calls, or to
       * reject the new incoming call.
       * <p>
       * You should trigger the display of the incoming call user interface for your application by
       * showing a {@link Notification} with a full-screen {@link Intent} specified.
       *
       * In your application code, you should create a {@link android.app.NotificationChannel} for
       * incoming call notifications from your app:
       * <pre><code>
       * NotificationChannel channel = new NotificationChannel(YOUR_CHANNEL_ID, "Incoming Calls",
       *          NotificationManager.IMPORTANCE_MAX);
       * // other channel setup stuff goes here.
       *
       * // We'll use the default system ringtone for our incoming call notification channel.  You can
       * // use your own audio resource here.
       * Uri ringtoneUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE);
       * channel.setSound(ringtoneUri, new AudioAttributes.Builder()
       *          // Setting the AudioAttributes is important as it identifies the purpose of your
       *          // notification sound.
       *          .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
       *          .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
       *      .build());
       *
       * NotificationManager mgr = getSystemService(NotificationManager.class);
       * mgr.createNotificationChannel(channel);
       * </code></pre>
       * When it comes time to post a notification for your incoming call, ensure it uses your
       * incoming call {@link android.app.NotificationChannel}.
       * <pre><code>
       *     // Create an intent which triggers your fullscreen incoming call user interface.
       *     Intent intent = new Intent(Intent.ACTION_MAIN, null);
       *     intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
       *     intent.setClass(context, YourIncomingCallActivity.class);
       *     PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, 0);
       *
       *     // Build the notification as an ongoing high priority item; this ensures it will show as
       *     // a heads up notification which slides down over top of the current content.
       *     final Notification.Builder builder = new Notification.Builder(context);
       *     builder.setOngoing(true);
       *     builder.setPriority(Notification.PRIORITY_HIGH);
       *
       *     // Set notification content intent to take user to fullscreen UI if user taps on the
       *     // notification body.
       *     builder.setContentIntent(pendingIntent);
       *     // Set full screen intent to trigger display of the fullscreen UI when the notification
       *     // manager deems it appropriate.
       *     builder.setFullScreenIntent(pendingIntent, true);
       *
       *     // Setup notification content.
       *     builder.setSmallIcon( yourIconResourceId );
       *     builder.setContentTitle("Your notification title");
       *     builder.setContentText("Your notification content.");
       *
       *     // Set notification as insistent to cause your ringtone to loop.
       *     Notification notification = builder.build();
       *     notification.flags |= Notification.FLAG_INSISTENT;
       *
       *     // Use builder.addAction(..) to add buttons to answer or reject the call.
       *     NotificationManager notificationManager = mContext.getSystemService(
       *         NotificationManager.class);
       *     notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, notification);
       * </code></pre>
       */
      public void onShowIncomingCallUi() {}
  
      /**
       * Notifies this {@link Connection} that the user has requested an RTT session.
       * The connection service should call {@link #sendRttInitiationSuccess} or
       * {@link #sendRttInitiationFailure} to inform Telecom of the success or failure of the
       * request, respectively.
       * @param rttTextStream The object that should be used to send text to or receive text from
       *                      the in-call app.
       */
      public void onStartRtt(@NonNull RttTextStream rttTextStream) {}
  
      /**
       * Notifies this {@link Connection} that it should terminate any existing RTT communication
       * channel. No response to Telecom is needed for this method.
       */
      public void onStopRtt() {}
  
      /**
       * Notifies this connection of a response to a previous remotely-initiated RTT upgrade
       * request sent via {@link #sendRemoteRttRequest}. Acceptance of the request is
       * indicated by the supplied {@link RttTextStream} being non-null, and rejection is
       * indicated by {@code rttTextStream} being {@code null}
       * @param rttTextStream The object that should be used to send text to or receive text from
       *                      the in-call app.
       */
      public void handleRttUpgradeResponse(@Nullable RttTextStream rttTextStream) {}
  
      static String toLogSafePhoneNumber(String number) {
          // For unknown number, log empty string.
          if (number == null) {
              return "";
          }
  
          if (PII_DEBUG) {
              // When PII_DEBUG is true we emit PII.
              return number;
          }
  
          // Do exactly same thing as Uri#toSafeString() does, which will enable us to compare
          // sanitized phone numbers.
          StringBuilder builder = new StringBuilder();
          for (int i = 0; i < number.length(); i++) {
              char c = number.charAt(i);
              if (c == '-' || c == '@' || c == '.') {
                  builder.append(c);
              } else {
                  builder.append('x');
              }
          }
          return builder.toString();
      }
  
      private void setState(int state) {
          checkImmutable();
          if (mState == STATE_DISCONNECTED && mState != state) {
              Log.d(this, "Connection already DISCONNECTED; cannot transition out of this state.");
              return;
          }
          if (mState != state) {
              Log.d(this, "setState: %s", stateToString(state));
              mState = state;
              onStateChanged(state);
              for (Listener l : mListeners) {
                  l.onStateChanged(this, state);
              }
          }
      }
  
      private static class FailureSignalingConnection extends Connection {
          private boolean mImmutable = false;
          public FailureSignalingConnection(DisconnectCause disconnectCause) {
              setDisconnected(disconnectCause);
              mImmutable = true;
          }
  
          public void checkImmutable() {
              if (mImmutable) {
                  throw new UnsupportedOperationException("Connection is immutable");
              }
          }
      }
  
      /**
       * Return a {@code Connection} which represents a failed connection attempt. The returned
       * {@code Connection} will have a {@link android.telecom.DisconnectCause} and as specified,
       * and a {@link #getState()} of {@link #STATE_DISCONNECTED}.
       * <p>
       * The returned {@code Connection} can be assumed to {@link #destroy()} itself when appropriate,
       * so users of this method need not maintain a reference to its return value to destroy it.
       *
       * @param disconnectCause The disconnect cause, ({@see android.telecomm.DisconnectCause}).
       * @return A {@code Connection} which indicates failure.
       */
      public static Connection createFailedConnection(DisconnectCause disconnectCause) {
          return new FailureSignalingConnection(disconnectCause);
      }
  
      /**
       * Override to throw an {@link UnsupportedOperationException} if this {@code Connection} is
       * not intended to be mutated, e.g., if it is a marker for failure. Only for framework use;
       * this should never be un-@hide-den.
       *
       * @hide
       */
      public void checkImmutable() {}
  
      /**
       * Return a {@code Connection} which represents a canceled connection attempt. The returned
       * {@code Connection} will have state {@link #STATE_DISCONNECTED}, and cannot be moved out of
       * that state. This connection should not be used for anything, and no other
       * {@code Connection}s should be attempted.
       * <p>
       * so users of this method need not maintain a reference to its return value to destroy it.
       *
       * @return A {@code Connection} which indicates that the underlying connection should
       * be canceled.
       */
      public static Connection createCanceledConnection() {
          return new FailureSignalingConnection(new DisconnectCause(DisconnectCause.CANCELED));
      }
  
      private final void fireOnConferenceableConnectionsChanged() {
          for (Listener l : mListeners) {
              l.onConferenceablesChanged(this, getConferenceables());
          }
      }
  
      private final void fireConferenceChanged() {
          for (Listener l : mListeners) {
              l.onConferenceChanged(this, mConference);
          }
      }
  
      private final void clearConferenceableList() {
          for (Conferenceable c : mConferenceables) {
              if (c instanceof Connection) {
                  Connection connection = (Connection) c;
                  connection.removeConnectionListener(mConnectionDeathListener);
              } else if (c instanceof Conference) {
                  Conference conference = (Conference) c;
                  conference.removeListener(mConferenceDeathListener);
              }
          }
          mConferenceables.clear();
      }
  
      /**
       * Handles a change to extras received from Telecom.
       *
       * @param extras The new extras.
       * @hide
       */
      final void handleExtrasChanged(Bundle extras) {
          Bundle b = null;
          synchronized (mExtrasLock) {
              mExtras = extras;
              if (mExtras != null) {
                  b = new Bundle(mExtras);
              }
          }
          onExtrasChanged(b);
      }
  
      /**
       * Notifies listeners that the merge request failed.
       *
       * @hide
       */
      protected final void notifyConferenceMergeFailed() {
          for (Listener l : mListeners) {
              l.onConferenceMergeFailed(this);
          }
      }
  
      /**
       * Notifies listeners of a change to conference participant(s).
       *
       * @param conferenceParticipants The participants.
       * @hide
       */
      protected final void updateConferenceParticipants(
              List<ConferenceParticipant> conferenceParticipants) {
          for (Listener l : mListeners) {
              l.onConferenceParticipantsChanged(this, conferenceParticipants);
          }
      }
  
      /**
       * Notifies listeners that a conference call has been started.
       * @hide
       */
      protected void notifyConferenceStarted() {
          for (Listener l : mListeners) {
              l.onConferenceStarted();
          }
      }
  
      /**
       * Notifies listeners when a change has occurred to the Connection which impacts its ability to
       * be a part of a conference call.
       * @param isConferenceSupported {@code true} if the connection supports being part of a
       *      conference call, {@code false} otherwise.
       * @hide
       */
      protected void notifyConferenceSupportedChanged(boolean isConferenceSupported) {
          for (Listener l : mListeners) {
              l.onConferenceSupportedChanged(this, isConferenceSupported);
          }
      }
  
      /**
       * Notifies listeners when phone account is changed. For example, when the PhoneAccount is
       * changed due to an emergency call being redialed.
       * @param pHandle The new PhoneAccountHandle for this connection.
       * @hide
       */
      public void notifyPhoneAccountChanged(PhoneAccountHandle pHandle) {
          for (Listener l : mListeners) {
              l.onPhoneAccountChanged(this, pHandle);
          }
      }
  
      /**
       * Sets the {@link PhoneAccountHandle} associated with this connection.
       *
       * @hide
       */
      public void setPhoneAccountHandle(PhoneAccountHandle phoneAccountHandle) {
          if (mPhoneAccountHandle != phoneAccountHandle) {
              mPhoneAccountHandle = phoneAccountHandle;
              notifyPhoneAccountChanged(phoneAccountHandle);
          }
      }
  
      /**
       * Returns the {@link PhoneAccountHandle} associated with this connection.
       *
       * @hide
       */
      public PhoneAccountHandle getPhoneAccountHandle() {
          return mPhoneAccountHandle;
      }
  
      /**
       * Sends an event associated with this {@code Connection} with associated event extras to the
       * {@link InCallService}.
       * <p>
       * Connection events are used to communicate point in time information from a
       * {@link ConnectionService} to a {@link InCallService} implementations.  An example of a
       * custom connection event includes notifying the UI when a WIFI call has been handed over to
       * LTE, which the InCall UI might use to inform the user that billing charges may apply.  The
       * Android Telephony framework will send the {@link #EVENT_CALL_MERGE_FAILED} connection event
       * when a call to {@link Call#mergeConference()} has failed to complete successfully.  A
       * connection event could also be used to trigger UI in the {@link InCallService} which prompts
       * the user to make a choice (e.g. whether they want to incur roaming costs for making a call),
       * which is communicated back via {@link Call#sendCallEvent(String, Bundle)}.
       * <p>
       * Events are exposed to {@link InCallService} implementations via
       * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
       * <p>
       * No assumptions should be made as to how an In-Call UI or service will handle these events.
       * The {@link ConnectionService} must assume that the In-Call UI could even chose to ignore
       * some events altogether.
       * <p>
       * Events should be fully qualified (e.g. {@code com.example.event.MY_EVENT}) to avoid
       * conflicts between {@link ConnectionService} implementations.  Further, custom
       * {@link ConnectionService} implementations shall not re-purpose events in the
       * {@code android.*} namespace, nor shall they define new event types in this namespace.  When
       * defining a custom event type, ensure the contents of the extras {@link Bundle} is clearly
       * defined.  Extra keys for this bundle should be named similar to the event type (e.g.
       * {@code com.example.extra.MY_EXTRA}).
       * <p>
       *  When defining events and the associated extras, it is important to keep their behavior
       * consistent when the associated {@link ConnectionService} is updated.  Support for deprecated
       * events/extras should me maintained to ensure backwards compatibility with older
       * {@link InCallService} implementations which were built to support the older behavior.
       *
       * @param event The connection event.
       * @param extras Optional bundle containing extra information associated with the event.
       */
      public void sendConnectionEvent(String event, Bundle extras) {
          for (Listener l : mListeners) {
              l.onConnectionEvent(this, event, extras);
          }
      }
  
      /**
       * @return The direction of the call.
       * @hide
       */
      public final @Call.Details.CallDirection int getCallDirection() {
          return mCallDirection;
      }
  
      /**
       * Sets the direction of this connection.
       * @param callDirection The direction of this connection.
       * @hide
       */
      public void setCallDirection(@Call.Details.CallDirection int callDirection) {
          mCallDirection = callDirection;
      }
  }
  