/*
* Copyright (C) 2011 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 com.android.phone;
import com.android.phone.Constants.CallStatusCode;
import android.content.Context;
import android.content.Intent;
import android.graphics.drawable.Drawable;
import android.net.Uri;
import android.text.TextUtils;
import android.util.Log;
/**
* Helper class to keep track of "persistent state" of the in-call UI.
*
* The onscreen appearance of the in-call UI mostly depends on the current
* Call/Connection state, which is owned by the telephony framework. But
* there's some application-level "UI state" too, which lives here in the
* phone app.
*
* This application-level state information is *not* maintained by the
* InCallScreen, since it needs to persist throughout an entire phone call,
* not just a single resume/pause cycle of the InCallScreen. So instead, that
* state is stored here, in a singleton instance of this class.
*
* The state kept here is a high-level abstraction of in-call UI state: we
* don't know about implementation details like specific widgets or strings or
* resources, but we do understand higher level concepts (for example "is the
* dialpad visible") and high-level modes (like InCallScreenMode) and error
* conditions (like CallStatusCode).
*
* @see InCallControlState for a separate collection of "UI state" that
* controls all the onscreen buttons of the in-call UI, based on the state of
* the telephony layer.
*
* The singleton instance of this class is owned by the PhoneApp instance.
*/
public class InCallUiState {
private static final String TAG = "InCallUiState";
private static final boolean DBG = false;
/** The singleton InCallUiState instance. */
private static InCallUiState sInstance;
private Context mContext;
/**
* Initialize the singleton InCallUiState instance.
*
* This is only done once, at startup, from PhoneApp.onCreate().
* From then on, the InCallUiState instance is available via the
* PhoneApp's public "inCallUiState" field, which is why there's no
* getInstance() method here.
*/
/* package */ static InCallUiState init(Context context) {
synchronized (InCallUiState.class) {
if (sInstance == null) {
sInstance = new InCallUiState(context);
} else {
Log.wtf(TAG, "init() called multiple times! sInstance = " + sInstance);
}
return sInstance;
}
}
/**
* Private constructor (this is a singleton).
* @see init()
*/
private InCallUiState(Context context) {
mContext = context;
}
//
// (1) High-level state of the whole in-call UI
//
/** High-level "modes" of the in-call UI. */
public enum InCallScreenMode {
/**
* Normal in-call UI elements visible.
*/
NORMAL,
/**
* "Manage conference" UI is visible, totally replacing the
* normal in-call UI.
*/
MANAGE_CONFERENCE,
/**
* Non-interactive UI state. Call card is visible,
* displaying information about the call that just ended.
*/
CALL_ENDED,
/**
* Normal OTA in-call UI elements visible.
*/
OTA_NORMAL,
/**
* OTA call ended UI visible, replacing normal OTA in-call UI.
*/
OTA_ENDED,
/**
* Default state when not on call
*/
UNDEFINED
}
/** Current high-level "mode" of the in-call UI. */
InCallScreenMode inCallScreenMode = InCallScreenMode.UNDEFINED;
//
// (2) State of specific UI elements
//
/**
* Is the onscreen twelve-key dialpad visible?
*/
boolean showDialpad;
/**
* The contents of the twelve-key dialpad's "digits" display, which is
* visible only when the dialpad itself is visible.
*
* (This is basically the "history" of DTMF digits you've typed so far
* in the current call. It's cleared out any time a new call starts,
* to make sure the digits don't persist between two separate calls.)
*/
String dialpadDigits;
//
// (3) Error / diagnostic indications
//
// This section provides an abstract concept of an "error status
// indication" for some kind of exceptional condition that needs to be
// communicated to the user, in the context of the in-call UI.
//
// If mPendingCallStatusCode is any value other than SUCCESS, that
// indicates that the in-call UI needs to display a dialog to the user
// with the specified title and message text.
//
// When an error occurs outside of the InCallScreen itself (like
// during CallController.placeCall() for example), we inform the user
// by doing the following steps:
//
// (1) set the "pending call status code" to a value other than SUCCESS
// (based on the specific error that happened)
// (2) force the InCallScreen to be launched (or relaunched)
// (3) InCallScreen.onResume() will notice that pending call status code
// is set, and will actually bring up the desired dialog.
//
// Watch out: any time you set (or change!) the pending call status code
// field you must be sure to always (re)launch the InCallScreen.
//
// Finally, the InCallScreen itself is responsible for resetting the
// pending call status code, when the user dismisses the dialog (like by
// hitting the OK button or pressing Back). The pending call status code
// field is NOT cleared simply by the InCallScreen being paused or
// finished, since the resulting dialog needs to persist across
// orientation changes or if the screen turns off.
// TODO: other features we might eventually need here:
//
// - Some error status messages stay in force till reset,
// others may automatically clear themselves after
// a fixed delay
//
// - Some error statuses may be visible as a dialog with an OK
// button (like "call failed"), others may be an indefinite
// progress dialog (like "turning on radio for emergency call").
//
// - Eventually some error statuses may have extra actions (like a
// "retry call" button that we might provide at the bottom of the
// "call failed because you have no signal" dialog.)
/**
* The current pending "error status indication" that we need to
* display to the user.
*
* If this field is set to a value other than SUCCESS, this indicates to
* the InCallScreen that we need to show some kind of message to the user
* (usually an error dialog) based on the specified status code.
*/
private CallStatusCode mPendingCallStatusCode = CallStatusCode.SUCCESS;
/**
* @return true if there's a pending "error status indication"
* that we need to display to the user.
*/
public boolean hasPendingCallStatusCode() {
if (DBG) log("hasPendingCallStatusCode() ==> "
+ (mPendingCallStatusCode != CallStatusCode.SUCCESS));
return (mPendingCallStatusCode != CallStatusCode.SUCCESS);
}
/**
* @return the pending "error status indication" code
* that we need to display to the user.
*/
public CallStatusCode getPendingCallStatusCode() {
if (DBG) log("getPendingCallStatusCode() ==> " + mPendingCallStatusCode);
return mPendingCallStatusCode;
}
/**
* Sets the pending "error status indication" code.
*/
public void setPendingCallStatusCode(CallStatusCode status) {
if (DBG) log("setPendingCallStatusCode( " + status + " )...");
if (mPendingCallStatusCode != CallStatusCode.SUCCESS) {
// Uh oh: mPendingCallStatusCode is already set to some value
// other than SUCCESS (which indicates that there was some kind of
// failure), and now we're trying to indicate another (potentially
// different) failure. But we can only indicate one failure at a
// time to the user, so the previous pending code is now going to
// be lost.
Log.w(TAG, "setPendingCallStatusCode: setting new code " + status
+ ", but a previous code " + mPendingCallStatusCode
+ " was already pending!");
}
mPendingCallStatusCode = status;
}
/**
* Clears out the pending "error status indication" code.
*
* This indicates that there's no longer any error or "exceptional
* condition" that needs to be displayed to the user. (Typically, this
* method is called when the user dismisses the error dialog that came up
* because of a previous call status code.)
*/
public void clearPendingCallStatusCode() {
if (DBG) log("clearPendingCallStatusCode()...");
mPendingCallStatusCode = CallStatusCode.SUCCESS;
}
/**
* Flag used to control the CDMA-specific "call lost" dialog.
*
* If true, that means that if the *next* outgoing call fails with an
* abnormal disconnection cause, we need to display the "call lost"
* dialog. (Normally, in CDMA we handle some types of call failures
* by automatically retrying the call. This flag is set to true when
* we're about to auto-retry, which means that if the *retry* also
* fails we'll give up and display an error.)
* See the logic in InCallScreen.onDisconnect() for the full story.
*
* TODO: the state machine that maintains the needToShowCallLostDialog
* flag in InCallScreen.onDisconnect() should really be moved into the
* CallController. Then we can get rid of this extra flag, and
* instead simply use the CallStatusCode value CDMA_CALL_LOST to
* trigger the "call lost" dialog.
*/
boolean needToShowCallLostDialog;
//
// Progress indications
//
/**
* Possible messages we might need to display along with
* an indefinite progress spinner.
*/
public enum ProgressIndicationType {
/**
* No progress indication needs to be shown.
*/
NONE,
/**
* Shown when making an emergency call from airplane mode;
* see CallController$EmergencyCallHelper.
*/
TURNING_ON_RADIO,
/**
* Generic "retrying" state. (Specifically, this is shown while
* retrying after an initial failure from the "emergency call from
* airplane mode" sequence.)
*/
RETRYING
}
/**
* The current progress indication that should be shown
* to the user. Any value other than NONE will cause the InCallScreen
* to bring up an indefinite progress spinner along with a message
* corresponding to the specified ProgressIndicationType.
*/
private ProgressIndicationType progressIndication = ProgressIndicationType.NONE;
/** Sets the current progressIndication. */
public void setProgressIndication(ProgressIndicationType value) {
progressIndication = value;
}
/** Clears the current progressIndication. */
public void clearProgressIndication() {
progressIndication = ProgressIndicationType.NONE;
}
/**
* @return the current progress indication type, or ProgressIndicationType.NONE
* if no progress indication is currently active.
*/
public ProgressIndicationType getProgressIndication() {
return progressIndication;
}
/** @return true if a progress indication is currently active. */
public boolean isProgressIndicationActive() {
return (progressIndication != ProgressIndicationType.NONE);
}
//
// (4) Optional overlay when a 3rd party "provider" is used.
// @see InCallScreen.updateProviderOverlay()
//
// TODO: maybe isolate all the provider-overlay-related stuff out to a
// separate inner class?
boolean providerOverlayVisible;
CharSequence providerLabel;
Drawable providerIcon;
Uri providerGatewayUri;
// The formatted address extracted from mProviderGatewayUri. User visible.
String providerAddress;
/**
* Set the fields related to the provider support
* based on the specified intent.
*/
public void setProviderOverlayInfo(Intent intent) {
providerLabel = PhoneUtils.getProviderLabel(mContext, intent);
providerIcon = PhoneUtils.getProviderIcon(mContext, intent);
providerGatewayUri = PhoneUtils.getProviderGatewayUri(intent);
providerAddress = PhoneUtils.formatProviderUri(providerGatewayUri);
providerOverlayVisible = true;
// ...but if any of the "required" fields are missing, completely
// disable the overlay.
if (TextUtils.isEmpty(providerLabel) || providerIcon == null ||
providerGatewayUri == null || TextUtils.isEmpty(providerAddress)) {
clearProviderOverlayInfo();
}
}
/**
* Clear all the fields related to the provider support.
*/
public void clearProviderOverlayInfo() {
providerOverlayVisible = false;
providerLabel = null;
providerIcon = null;
providerGatewayUri = null;
providerAddress = null;
}
/**
* "Call origin" of the most recent phone call.
*
* Watch out: right now this is only used to determine where the user should go after the phone
* call. See also {@link InCallScreen} for more detail. There is *no* specific specification
* about how this variable will be used.
*
* @see PhoneApp#setLatestActiveCallOrigin(String)
* @see PhoneApp#createPhoneEndIntentUsingCallOrigin()
*
* TODO: we should determine some public behavior for this variable.
*/
String latestActiveCallOrigin;
//
// Debugging
//
public void dumpState() {
log("dumpState():");
log(" - showDialpad: " + showDialpad);
if (hasPendingCallStatusCode()) {
log(" - status indication is pending!");
log(" - pending call status code = " + mPendingCallStatusCode);
} else {
log(" - pending call status code: none");
}
log(" - progressIndication: " + progressIndication);
if (providerOverlayVisible) {
log(" - provider overlay VISIBLE: "
+ providerLabel + " / "
+ providerIcon + " / "
+ providerGatewayUri + " / "
+ providerAddress);
} else {
log(" - provider overlay: none");
}
log(" - latestActiveCallOrigin: " + latestActiveCallOrigin);
}
private static void log(String msg) {
Log.d(TAG, msg);
}
}