Renaming Telecomm to Telecom.
- Changing package from android.telecomm to android.telecom
- Changing package from com.android.telecomm to
com.android.server.telecomm.
- Renaming TelecommManager to TelecomManager.
Bug: 17364651
Change-Id: I192cb5d189f55db012ea72ee82ccc5aedbc21638
diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
new file mode 100644
index 0000000..5f63af3
--- /dev/null
+++ b/telecomm/java/android/telecom/Connection.java
@@ -0,0 +1,1129 @@
+/*
+ * 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 com.android.internal.telecom.IVideoCallback;
+import com.android.internal.telecom.IVideoProvider;
+
+import android.net.Uri;
+import android.os.Handler;
+import android.os.IBinder;
+import android.os.Message;
+import android.os.RemoteException;
+import android.telephony.DisconnectCause;
+import android.view.Surface;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Represents a connection to a remote endpoint that carries voice 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.
+ */
+public abstract class Connection {
+
+ public static final int STATE_INITIALIZING = 0;
+
+ public static final int STATE_NEW = 1;
+
+ public static final int STATE_RINGING = 2;
+
+ public static final int STATE_DIALING = 3;
+
+ public static final int STATE_ACTIVE = 4;
+
+ public static final int STATE_HOLDING = 5;
+
+ public static final int STATE_DISCONNECTED = 6;
+
+ // Flag controlling whether PII is emitted into the logs
+ private static final boolean PII_DEBUG = Log.isLoggable(android.util.Log.DEBUG);
+
+ /** @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, int cause, String message) {}
+ public void onPostDialWait(Connection c, String remaining) {}
+ public void onRingbackRequested(Connection c, boolean ringback) {}
+ public void onDestroyed(Connection c) {}
+ public void onCallCapabilitiesChanged(Connection c, int callCapabilities) {}
+ public void onVideoProviderChanged(
+ Connection c, VideoProvider videoProvider) {}
+ public void onAudioModeIsVoipChanged(Connection c, boolean isVoip) {}
+ public void onStatusHintsChanged(Connection c, StatusHints statusHints) {}
+ public void onConferenceableConnectionsChanged(
+ Connection c, List<Connection> conferenceableConnections) {}
+ public void onConferenceChanged(Connection c, Conference conference) {}
+ }
+
+ /** @hide */
+ public static abstract class VideoProvider {
+
+ /**
+ * Video is not being received (no protocol pause was issued).
+ */
+ public static final int SESSION_EVENT_RX_PAUSE = 1;
+
+ /**
+ * Video reception has resumed after a SESSION_EVENT_RX_PAUSE.
+ */
+ 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.
+ */
+ 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.
+ */
+ public static final int SESSION_EVENT_TX_STOP = 4;
+
+ /**
+ * A camera failure has occurred for the selected camera. The In-Call UI can use this as a
+ * cue to inform the user the camera is not available.
+ */
+ public static final int SESSION_EVENT_CAMERA_FAILURE = 5;
+
+ /**
+ * Issued after {@code SESSION_EVENT_CAMERA_FAILURE} when the camera is once again ready for
+ * operation. The In-Call UI can use this as a cue to inform the user that the camera has
+ * become available again.
+ */
+ public static final int SESSION_EVENT_CAMERA_READY = 6;
+
+ /**
+ * 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;
+
+ private static final int MSG_SET_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_CALL_DATA_USAGE = 10;
+ private static final int MSG_SET_PAUSE_IMAGE = 11;
+
+ private final VideoProvider.VideoProviderHandler
+ mMessageHandler = new VideoProvider.VideoProviderHandler();
+ private final VideoProvider.VideoProviderBinder mBinder;
+ private IVideoCallback mVideoCallback;
+
+ /**
+ * Default handler used to consolidate binder method calls onto a single thread.
+ */
+ private final class VideoProviderHandler extends Handler {
+ @Override
+ public void handleMessage(Message msg) {
+ switch (msg.what) {
+ case MSG_SET_VIDEO_CALLBACK:
+ mVideoCallback = IVideoCallback.Stub.asInterface((IBinder) msg.obj);
+ break;
+ case MSG_SET_CAMERA:
+ onSetCamera((String) msg.obj);
+ 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:
+ onSendSessionModifyRequest((VideoProfile) msg.obj);
+ break;
+ case MSG_SEND_SESSION_MODIFY_RESPONSE:
+ onSendSessionModifyResponse((VideoProfile) msg.obj);
+ break;
+ case MSG_REQUEST_CAMERA_CAPABILITIES:
+ onRequestCameraCapabilities();
+ break;
+ case MSG_REQUEST_CALL_DATA_USAGE:
+ onRequestCallDataUsage();
+ break;
+ case MSG_SET_PAUSE_IMAGE:
+ onSetPauseImage((String) msg.obj);
+ break;
+ default:
+ break;
+ }
+ }
+ }
+
+ /**
+ * IVideoProvider stub implementation.
+ */
+ private final class VideoProviderBinder extends IVideoProvider.Stub {
+ public void setVideoCallback(IBinder videoCallbackBinder) {
+ mMessageHandler.obtainMessage(
+ MSG_SET_VIDEO_CALLBACK, videoCallbackBinder).sendToTarget();
+ }
+
+ public void setCamera(String cameraId) {
+ mMessageHandler.obtainMessage(MSG_SET_CAMERA, cameraId).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).sendToTarget();
+ }
+
+ public void setZoom(float value) {
+ mMessageHandler.obtainMessage(MSG_SET_ZOOM, value).sendToTarget();
+ }
+
+ public void sendSessionModifyRequest(VideoProfile requestProfile) {
+ mMessageHandler.obtainMessage(
+ MSG_SEND_SESSION_MODIFY_REQUEST, requestProfile).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_CALL_DATA_USAGE).sendToTarget();
+ }
+
+ public void setPauseImage(String uri) {
+ mMessageHandler.obtainMessage(MSG_SET_PAUSE_IMAGE, uri).sendToTarget();
+ }
+ }
+
+ public VideoProvider() {
+ mBinder = new VideoProvider.VideoProviderBinder();
+ }
+
+ /**
+ * Returns binder object which can be used across IPC methods.
+ * @hide
+ */
+ public final IVideoProvider getInterface() {
+ return mBinder;
+ }
+
+ /**
+ * Sets the camera to be used for video recording in a video call.
+ *
+ * @param cameraId The id of the camera.
+ */
+ public abstract void onSetCamera(String cameraId);
+
+ /**
+ * 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.
+ *
+ * @param surface The surface.
+ */
+ public abstract void onSetPreviewSurface(Surface surface);
+
+ /**
+ * Sets the surface to be used for displaying the video received from the remote device.
+ *
+ * @param surface The 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.
+ *
+ * @param rotation The device orientation, in degrees.
+ */
+ public abstract void onSetDeviceOrientation(int rotation);
+
+ /**
+ * Sets camera zoom ratio.
+ *
+ * @param value The camera zoom ratio.
+ */
+ public abstract void onSetZoom(float value);
+
+ /**
+ * Issues a request to modify the properties of the current session. The request is
+ * sent to the remote device where it it handled by the In-Call UI.
+ * Some examples of session modification requests: upgrade call from audio to video,
+ * downgrade call from video to audio, pause video.
+ *
+ * @param requestProfile The requested call video properties.
+ */
+ public abstract void onSendSessionModifyRequest(VideoProfile requestProfile);
+
+ /**te
+ * Provides a response to a request to change the current call session video
+ * properties.
+ * This is in response to a request the InCall UI has received via the InCall UI.
+ *
+ * @param responseProfile The response call video properties.
+ */
+ public abstract void onSendSessionModifyResponse(VideoProfile responseProfile);
+
+ /**
+ * Issues a request to the video provider to retrieve the camera capabilities.
+ * Camera capabilities are reported back to the caller via the In-Call UI.
+ */
+ public abstract void onRequestCameraCapabilities();
+
+ /**
+ * Issues a request to the video telephony framework to retrieve the cumulative data usage
+ * for the current call. Data usage is reported back to the caller via the
+ * InCall UI.
+ */
+ public abstract void onRequestCallDataUsage();
+
+ /**
+ * Provides the video telephony framework with the URI of an image to be displayed to remote
+ * devices when the video signal is paused.
+ *
+ * @param uri URI of image to display.
+ */
+ public abstract void onSetPauseImage(String uri);
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * @param videoProfile The requested video call profile.
+ */
+ public void receiveSessionModifyRequest(VideoProfile videoProfile) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.receiveSessionModifyRequest(videoProfile);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * @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}
+ * @param requestedProfile The original request which was sent to the remote device.
+ * @param responseProfile The actual profile changes made by the remote device.
+ */
+ public void receiveSessionModifyResponse(int status,
+ VideoProfile requestedProfile, VideoProfile responseProfile) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.receiveSessionModifyResponse(
+ status, requestedProfile, responseProfile);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * 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}
+ *
+ * @param event The event.
+ */
+ public void handleCallSessionEvent(int event) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.handleCallSessionEvent(event);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * @param width The updated peer video width.
+ * @param height The updated peer video height.
+ */
+ public void changePeerDimensions(int width, int height) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.changePeerDimensions(width, height);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * @param dataUsage The updated data usage.
+ */
+ public void changeCallDataUsage(int dataUsage) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.changeCallDataUsage(dataUsage);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+
+ /**
+ * Invokes callback method defined in In-Call UI.
+ *
+ * @param cameraCapabilities The changed camera capabilities.
+ */
+ public void changeCameraCapabilities(CameraCapabilities cameraCapabilities) {
+ if (mVideoCallback != null) {
+ try {
+ mVideoCallback.changeCameraCapabilities(cameraCapabilities);
+ } catch (RemoteException ignored) {
+ }
+ }
+ }
+ }
+
+ private final Listener mConnectionDeathListener = new Listener() {
+ @Override
+ public void onDestroyed(Connection c) {
+ if (mConferenceableConnections.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<Connection> mConferenceableConnections = new ArrayList<>();
+ private final List<Connection> mUnmodifiableConferenceableConnections =
+ Collections.unmodifiableList(mConferenceableConnections);
+
+ private int mState = STATE_NEW;
+ private AudioState mAudioState;
+ private Uri mAddress;
+ private int mAddressPresentation;
+ private String mCallerDisplayName;
+ private int mCallerDisplayNamePresentation;
+ private boolean mRingbackRequested = false;
+ private int mCallCapabilities;
+ private VideoProvider mVideoProvider;
+ private boolean mAudioModeIsVoip;
+ private StatusHints mStatusHints;
+ private int mVideoState;
+ private int mDisconnectCause;
+ private String mDisconnectMessage;
+ private Conference mConference;
+ private ConnectionService mConnectionService;
+
+ /**
+ * Create a new Connection.
+ */
+ public Connection() {}
+
+ /**
+ * @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 call.
+ * Valid values: {@link VideoProfile.VideoState#AUDIO_ONLY},
+ * {@link VideoProfile.VideoState#BIDIRECTIONAL},
+ * {@link VideoProfile.VideoState#TX_ENABLED},
+ * {@link VideoProfile.VideoState#RX_ENABLED}.
+ *
+ * @return The video state of the call.
+ * @hide
+ */
+ public final int getVideoState() {
+ return mVideoState;
+ }
+
+ /**
+ * @return The audio state of the call, 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 AudioState getAudioState() {
+ return mAudioState;
+ }
+
+ /**
+ * @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;
+ }
+
+ /**
+ * @return The status hints for this connection.
+ */
+ public final StatusHints getStatusHints() {
+ return mStatusHints;
+ }
+
+ /**
+ * 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 int getDisconnectCause() {
+ return mDisconnectCause;
+ }
+
+ /**
+ * @return The disconnect message for this connection.
+ */
+ public final String getDisconnectMessage() {
+ return mDisconnectMessage;
+ }
+
+ /**
+ * Inform this Connection that the state of its audio output has been changed externally.
+ *
+ * @param state The new audio state.
+ * @hide
+ */
+ final void setAudioState(AudioState state) {
+ Log.d(this, "setAudioState %s", state);
+ mAudioState = state;
+ onAudioStateChanged(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 "STATE_INITIALIZING";
+ case STATE_NEW:
+ return "STATE_NEW";
+ case STATE_RINGING:
+ return "STATE_RINGING";
+ case STATE_DIALING:
+ return "STATE_DIALING";
+ case STATE_ACTIVE:
+ return "STATE_ACTIVE";
+ case STATE_HOLDING:
+ return "STATE_HOLDING";
+ case STATE_DISCONNECTED:
+ return "DISCONNECTED";
+ default:
+ Log.wtf(Connection.class, "Unknown state %d", state);
+ return "UNKNOWN";
+ }
+ }
+
+ /**
+ * Returns the connection's {@link PhoneCapabilities}
+ */
+ public final int getCallCapabilities() {
+ return mCallCapabilities;
+ }
+
+ /**
+ * 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) {
+ 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) {
+ 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.VideoState#AUDIO_ONLY},
+ * {@link VideoProfile.VideoState#BIDIRECTIONAL},
+ * {@link VideoProfile.VideoState#TX_ENABLED},
+ * {@link VideoProfile.VideoState#RX_ENABLED}.
+ *
+ * @param videoState The new video state.
+ * @hide
+ */
+ public final void setVideoState(int videoState) {
+ Log.d(this, "setVideoState %d", videoState);
+ mVideoState = videoState;
+ for (Listener l : mListeners) {
+ l.onVideoStateChanged(this, mVideoState);
+ }
+ }
+
+ /**
+ * Sets state to active (e.g., an ongoing call where two or more parties can actively
+ * communicate).
+ */
+ public final void setActive() {
+ setRingbackRequested(false);
+ setState(STATE_ACTIVE);
+ }
+
+ /**
+ * Sets state to ringing (e.g., an inbound ringing call).
+ */
+ public final void setRinging() {
+ setState(STATE_RINGING);
+ }
+
+ /**
+ * Sets state to initializing (this Connection is not yet ready to be used).
+ */
+ public final void setInitializing() {
+ setState(STATE_INITIALIZING);
+ }
+
+ /**
+ * Sets state to initialized (the Connection has been set up and is now ready to be used).
+ */
+ public final void setInitialized() {
+ setState(STATE_NEW);
+ }
+
+ /**
+ * Sets state to dialing (e.g., dialing an outbound call).
+ */
+ public final void setDialing() {
+ setState(STATE_DIALING);
+ }
+
+ /**
+ * Sets state to be on hold.
+ */
+ public final void setOnHold() {
+ setState(STATE_HOLDING);
+ }
+
+ /**
+ * Sets the video call provider.
+ * @param videoProvider The video provider.
+ * @hide
+ */
+ public final void setVideoProvider(VideoProvider videoProvider) {
+ mVideoProvider = videoProvider;
+ for (Listener l : mListeners) {
+ l.onVideoProviderChanged(this, videoProvider);
+ }
+ }
+
+ /** @hide */
+ public final VideoProvider getVideoProvider() {
+ return mVideoProvider;
+ }
+
+ /**
+ * Sets state to disconnected.
+ *
+ * @param cause The reason for the disconnection, any of
+ * {@link DisconnectCause}.
+ * @param message Optional call-service-provided message about the disconnect.
+ */
+ public final void setDisconnected(int cause, String message) {
+ mDisconnectCause = cause;
+ mDisconnectMessage = message;
+ setState(STATE_DISCONNECTED);
+ Log.d(this, "Disconnected with cause %d message %s", cause, message);
+ for (Listener l : mListeners) {
+ l.onDisconnected(this, cause, message);
+ }
+ }
+
+ /**
+ * TODO: Needs documentation.
+ */
+ public final void setPostDialWait(String remaining) {
+ for (Listener l : mListeners) {
+ l.onPostDialWait(this, remaining);
+ }
+ }
+
+ /**
+ * 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 call's audio stream.
+ *
+ * @param ringback Whether the ringback tone is to be played.
+ */
+ public final void setRingbackRequested(boolean ringback) {
+ if (mRingbackRequested != ringback) {
+ mRingbackRequested = ringback;
+ for (Listener l : mListeners) {
+ l.onRingbackRequested(this, ringback);
+ }
+ }
+ }
+
+ /**
+ * Sets the connection's {@link PhoneCapabilities}.
+ *
+ * @param callCapabilities The new call capabilities.
+ */
+ public final void setCallCapabilities(int callCapabilities) {
+ if (mCallCapabilities != callCapabilities) {
+ mCallCapabilities = callCapabilities;
+ for (Listener l : mListeners) {
+ l.onCallCapabilitiesChanged(this, mCallCapabilities);
+ }
+ }
+ }
+
+ /**
+ * 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) {
+ mAudioModeIsVoip = isVoip;
+ for (Listener l : mListeners) {
+ l.onAudioModeIsVoipChanged(this, isVoip);
+ }
+ }
+
+ /**
+ * 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) {
+ 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) {
+ 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 (!mConferenceableConnections.contains(c)) {
+ c.addConnectionListener(mConnectionDeathListener);
+ mConferenceableConnections.add(c);
+ }
+ }
+ fireOnConferenceableConnectionsChanged();
+ }
+
+ /**
+ * Obtains the connections with which this connection can be conferenced.
+ */
+ public final List<Connection> getConferenceableConnections() {
+ return mUnmodifiableConferenceableConnections;
+ }
+
+ /*
+ * @hide
+ */
+ public final void setConnectionService(ConnectionService connectionService) {
+ 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;
+ }
+ }
+
+ /**
+ * Sets the conference that this connection is a part of. This will fail if the connection is
+ * already part of a conference call. {@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) {
+ // 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();
+ }
+ }
+
+ /**
+ * Notifies this Connection that the {@link #getAudioState()} property has a new value.
+ *
+ * @param state The new call audio state.
+ */
+ public void onAudioStateChanged(AudioState 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 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.
+ *
+ * @param videoState The video state in which to answer the call.
+ * @hide
+ */
+ public void onAnswer(int videoState) {}
+
+ /**
+ * Notifies this Connection, which is in {@link #STATE_RINGING}, of
+ * a request to accept.
+ */
+ public void onAnswer() {
+ onAnswer(VideoProfile.VideoState.AUDIO_ONLY);
+ }
+
+ /**
+ * Notifies this Connection, which is in {@link #STATE_RINGING}, of
+ * a request to reject.
+ */
+ public void onReject() {}
+
+ /**
+ * Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.
+ */
+ public void onPostDialContinue(boolean proceed) {}
+
+ /**
+ * Merge this connection and the specified connection into a conference call. Once the
+ * connections are merged, the calls should be added to the an existing or new
+ * {@code Conference} instance. For new {@code Conference} instances, use
+ * {@code ConnectionService#addConference}.
+ *
+ * @param otherConnection The connection with which this connection should be conferenced.
+ */
+ public void onConferenceWith(Connection otherConnection) {}
+
+ 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) {
+ 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 {
+ public FailureSignalingConnection(int cause, String message) {
+ setDisconnected(cause, message);
+ }
+ }
+
+ /**
+ * Return a {@code Connection} which represents a failed connection attempt. The returned
+ * {@code Connection} will have a {@link #getDisconnectCause()} and
+ * {@link #getDisconnectMessage()} 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 cause The disconnect cause, ({@see DisconnectCause}).
+ * @param message A reason for why the connection failed (not intended to be shown to the user).
+ * @return A {@code Connection} which indicates failure.
+ */
+ public static Connection createFailedConnection(int cause, String message) {
+ return new FailureSignalingConnection(cause, message);
+ }
+
+ /**
+ * 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>
+ * 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.
+ *
+ * @return A {@code Connection} which indicates that the underlying call should be canceled.
+ */
+ public static Connection createCanceledConnection() {
+ return new FailureSignalingConnection(DisconnectCause.OUTGOING_CANCELED, null);
+ }
+
+ private final void fireOnConferenceableConnectionsChanged() {
+ for (Listener l : mListeners) {
+ l.onConferenceableConnectionsChanged(this, mConferenceableConnections);
+ }
+ }
+
+ private final void fireConferenceChanged() {
+ for (Listener l : mListeners) {
+ l.onConferenceChanged(this, mConference);
+ }
+ }
+
+ private final void clearConferenceableList() {
+ for (Connection c : mConferenceableConnections) {
+ c.removeConnectionListener(mConnectionDeathListener);
+ }
+ mConferenceableConnections.clear();
+ }
+}