telecomm/java/android/telecom/Phone.java

   1 /*
   2  * Copyright (C) 2013 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.telecom;
  18
  19 import android.annotation.SystemApi;
  20 import android.util.ArrayMap;
  21
  22 import java.util.Collections;
  23 import java.util.List;
  24 import java.util.Map;
  25 import java.util.Objects;
  26 import java.util.concurrent.CopyOnWriteArrayList;
  27
  28 /**
  29  * A unified virtual device providing a means of voice (and other) communication on a device.
  30  *
  31  * @hide
  32  * @deprecated Use {@link InCallService} directly instead of using this class.
  33  */
  34 @SystemApi
  35 @Deprecated
  36 public final class Phone {
  37
  38     public abstract static class Listener {
  39         /**
  40          * Called when the audio state changes.
  41          *
  42          * @param phone The {@code Phone} calling this method.
  43          * @param audioState The new {@link AudioState}.
  44          *
  45          * @deprecated Use {@link #onCallAudioStateChanged(Phone, CallAudioState)} instead.
  46          */
  47         @Deprecated
  48         public void onAudioStateChanged(Phone phone, AudioState audioState) { }
  49
  50         /**
  51          * Called when the audio state changes.
  52          *
  53          * @param phone The {@code Phone} calling this method.
  54          * @param callAudioState The new {@link CallAudioState}.
  55          */
  56         public void onCallAudioStateChanged(Phone phone, CallAudioState callAudioState) { }
  57
  58         /**
  59          * Called to bring the in-call screen to the foreground. The in-call experience should
  60          * respond immediately by coming to the foreground to inform the user of the state of
  61          * ongoing {@code Call}s.
  62          *
  63          * @param phone The {@code Phone} calling this method.
  64          * @param showDialpad If true, put up the dialpad when the screen is shown.
  65          */
  66         public void onBringToForeground(Phone phone, boolean showDialpad) { }
  67
  68         /**
  69          * Called when a {@code Call} has been added to this in-call session. The in-call user
  70          * experience should add necessary state listeners to the specified {@code Call} and
  71          * immediately start to show the user information about the existence
  72          * and nature of this {@code Call}. Subsequent invocations of {@link #getCalls()} will
  73          * include this {@code Call}.
  74          *
  75          * @param phone The {@code Phone} calling this method.
  76          * @param call A newly added {@code Call}.
  77          */
  78         public void onCallAdded(Phone phone, Call call) { }
  79
  80         /**
  81          * Called when a {@code Call} has been removed from this in-call session. The in-call user
  82          * experience should remove any state listeners from the specified {@code Call} and
  83          * immediately stop displaying any information about this {@code Call}.
  84          * Subsequent invocations of {@link #getCalls()} will no longer include this {@code Call}.
  85          *
  86          * @param phone The {@code Phone} calling this method.
  87          * @param call A newly removed {@code Call}.
  88          */
  89         public void onCallRemoved(Phone phone, Call call) { }
  90
  91         /**
  92          * Called when the {@code Phone} ability to add more calls changes.  If the phone cannot
  93          * support more calls then {@code canAddCall} is set to {@code false}.  If it can, then it
  94          * is set to {@code true}.
  95          *
  96          * @param phone The {@code Phone} calling this method.
  97          * @param canAddCall Indicates whether an additional call can be added.
  98          */
  99         public void onCanAddCallChanged(Phone phone, boolean canAddCall) { }
 100
 101         /**
 102          * Called to silence the ringer if a ringing call exists.
 103          *
 104          * @param phone The {@code Phone} calling this method.
 105          */
 106         public void onSilenceRinger(Phone phone) { }
 107     }
 108
 109     // A Map allows us to track each Call by its Telecom-specified call ID
 110     private final Map<String, Call> mCallByTelecomCallId = new ArrayMap<>();
 111
 112     // A List allows us to keep the Calls in a stable iteration order so that casually developed
 113     // user interface components do not incur any spurious jank
 114     private final List<Call> mCalls = new CopyOnWriteArrayList<>();
 115
 116     // An unmodifiable view of the above List can be safely shared with subclass implementations
 117     private final List<Call> mUnmodifiableCalls = Collections.unmodifiableList(mCalls);
 118
 119     private final InCallAdapter mInCallAdapter;
 120
 121     private CallAudioState mCallAudioState;
 122
 123     private final List<Listener> mListeners = new CopyOnWriteArrayList<>();
 124
 125     private boolean mCanAddCall = true;
 126
 127     Phone(InCallAdapter adapter) {
 128         mInCallAdapter = adapter;
 129     }
 130
 131     final void internalAddCall(ParcelableCall parcelableCall) {
 132         Call call = new Call(this, parcelableCall.getId(), mInCallAdapter,
 133                 parcelableCall.getState());
 134         mCallByTelecomCallId.put(parcelableCall.getId(), call);
 135         mCalls.add(call);
 136         checkCallTree(parcelableCall);
 137         call.internalUpdate(parcelableCall, mCallByTelecomCallId);
 138         fireCallAdded(call);
 139      }
 140
 141     final void internalRemoveCall(Call call) {
 142         mCallByTelecomCallId.remove(call.internalGetCallId());
 143         mCalls.remove(call);
 144
 145         InCallService.VideoCall videoCall = call.getVideoCall();
 146         if (videoCall != null) {
 147             videoCall.destroy();
 148         }
 149         fireCallRemoved(call);
 150     }
 151
 152     final void internalUpdateCall(ParcelableCall parcelableCall) {
 153          Call call = mCallByTelecomCallId.get(parcelableCall.getId());
 154          if (call != null) {
 155              checkCallTree(parcelableCall);
 156              call.internalUpdate(parcelableCall, mCallByTelecomCallId);
 157          }
 158      }
 159
 160     final void internalSetPostDialWait(String telecomId, String remaining) {
 161         Call call = mCallByTelecomCallId.get(telecomId);
 162         if (call != null) {
 163             call.internalSetPostDialWait(remaining);
 164         }
 165     }
 166
 167     final void internalCallAudioStateChanged(CallAudioState callAudioState) {
 168         if (!Objects.equals(mCallAudioState, callAudioState)) {
 169             mCallAudioState = callAudioState;
 170             fireCallAudioStateChanged(callAudioState);
 171         }
 172     }
 173
 174     final Call internalGetCallByTelecomId(String telecomId) {
 175         return mCallByTelecomCallId.get(telecomId);
 176     }
 177
 178     final void internalBringToForeground(boolean showDialpad) {
 179         fireBringToForeground(showDialpad);
 180     }
 181
 182     final void internalSetCanAddCall(boolean canAddCall) {
 183         if (mCanAddCall != canAddCall) {
 184             mCanAddCall = canAddCall;
 185             fireCanAddCallChanged(canAddCall);
 186         }
 187     }
 188
 189     final void internalSilenceRinger() {
 190         fireSilenceRinger();
 191     }
 192
 193     /**
 194      * Called to destroy the phone and cleanup any lingering calls.
 195      */
 196     final void destroy() {
 197         for (Call call : mCalls) {
 198             InCallService.VideoCall videoCall = call.getVideoCall();
 199             if (videoCall != null) {
 200                 videoCall.destroy();
 201             }
 202             if (call.getState() != Call.STATE_DISCONNECTED) {
 203                 call.internalSetDisconnected();
 204             }
 205         }
 206     }
 207
 208     /**
 209      * Adds a listener to this {@code Phone}.
 210      *
 211      * @param listener A {@code Listener} object.
 212      */
 213     public final void addListener(Listener listener) {
 214         mListeners.add(listener);
 215     }
 216
 217     /**
 218      * Removes a listener from this {@code Phone}.
 219      *
 220      * @param listener A {@code Listener} object.
 221      */
 222     public final void removeListener(Listener listener) {
 223         if (listener != null) {
 224             mListeners.remove(listener);
 225         }
 226     }
 227
 228     /**
 229      * Obtains the current list of {@code Call}s to be displayed by this in-call experience.
 230      *
 231      * @return A list of the relevant {@code Call}s.
 232      */
 233     public final List<Call> getCalls() {
 234         return mUnmodifiableCalls;
 235     }
 236
 237     /**
 238      * Returns if the {@code Phone} can support additional calls.
 239      *
 240      * @return Whether the phone supports adding more calls.
 241      */
 242     public final boolean canAddCall() {
 243         return mCanAddCall;
 244     }
 245
 246     /**
 247      * Sets the microphone mute state. When this request is honored, there will be change to
 248      * the {@link #getAudioState()}.
 249      *
 250      * @param state {@code true} if the microphone should be muted; {@code false} otherwise.
 251      */
 252     public final void setMuted(boolean state) {
 253         mInCallAdapter.mute(state);
 254     }
 255
 256     /**
 257      * Sets the audio route (speaker, bluetooth, etc...).  When this request is honored, there will
 258      * be change to the {@link #getAudioState()}.
 259      *
 260      * @param route The audio route to use.
 261      */
 262     public final void setAudioRoute(int route) {
 263         mInCallAdapter.setAudioRoute(route);
 264     }
 265
 266     /**
 267      * Turns the proximity sensor on. When this request is made, the proximity sensor will
 268      * become active, and the touch screen and display will be turned off when the user's face
 269      * is detected to be in close proximity to the screen. This operation is a no-op on devices
 270      * that do not have a proximity sensor.
 271      *
 272      * @hide
 273      */
 274     public final void setProximitySensorOn() {
 275         mInCallAdapter.turnProximitySensorOn();
 276     }
 277
 278     /**
 279      * Turns the proximity sensor off. When this request is made, the proximity sensor will
 280      * become inactive, and no longer affect the touch screen and display. This operation is a
 281      * no-op on devices that do not have a proximity sensor.
 282      *
 283      * @param screenOnImmediately If true, the screen will be turned on immediately if it was
 284      * previously off. Otherwise, the screen will only be turned on after the proximity sensor
 285      * is no longer triggered.
 286      *
 287      * @hide
 288      */
 289     public final void setProximitySensorOff(boolean screenOnImmediately) {
 290         mInCallAdapter.turnProximitySensorOff(screenOnImmediately);
 291     }
 292
 293     /**
 294      * Obtains the current phone call audio state of the {@code Phone}.
 295      *
 296      * @return An object encapsulating the audio state.
 297      * @deprecated Use {@link #getCallAudioState()} instead.
 298      */
 299     @Deprecated
 300     public final AudioState getAudioState() {
 301         return new AudioState(mCallAudioState);
 302     }
 303
 304     /**
 305      * Obtains the current phone call audio state of the {@code Phone}.
 306      *
 307      * @return An object encapsulating the audio state.
 308      */
 309     public final CallAudioState getCallAudioState() {
 310         return mCallAudioState;
 311     }
 312
 313     private void fireCallAdded(Call call) {
 314         for (Listener listener : mListeners) {
 315             listener.onCallAdded(this, call);
 316         }
 317     }
 318
 319     private void fireCallRemoved(Call call) {
 320         for (Listener listener : mListeners) {
 321             listener.onCallRemoved(this, call);
 322         }
 323     }
 324
 325     private void fireCallAudioStateChanged(CallAudioState audioState) {
 326         for (Listener listener : mListeners) {
 327             listener.onCallAudioStateChanged(this, audioState);
 328             listener.onAudioStateChanged(this, new AudioState(audioState));
 329         }
 330     }
 331
 332     private void fireBringToForeground(boolean showDialpad) {
 333         for (Listener listener : mListeners) {
 334             listener.onBringToForeground(this, showDialpad);
 335         }
 336     }
 337
 338     private void fireCanAddCallChanged(boolean canAddCall) {
 339         for (Listener listener : mListeners) {
 340             listener.onCanAddCallChanged(this, canAddCall);
 341         }
 342     }
 343
 344     private void fireSilenceRinger() {
 345         for (Listener listener : mListeners) {
 346             listener.onSilenceRinger(this);
 347         }
 348     }
 349
 350     private void checkCallTree(ParcelableCall parcelableCall) {
 351         if (parcelableCall.getChildCallIds() != null) {
 352             for (int i = 0; i < parcelableCall.getChildCallIds().size(); i++) {
 353                 if (!mCallByTelecomCallId.containsKey(parcelableCall.getChildCallIds().get(i))) {
 354                     Log.wtf(this, "ParcelableCall %s has nonexistent child %s",
 355                             parcelableCall.getId(), parcelableCall.getChildCallIds().get(i));
 356                 }
 357             }
 358         }
 359     }
 360 }