Telecom API council changes.
- adding more javadocs.
- fixing javadoc on isEnabled
- renaming to CONFIGURE_PHONE_ACCOUNT
Bug: 21573551
Change-Id: Ice035b8573a08ea18181a73c9e9a462520a934f1
diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index 6055211..721b718 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -40,7 +40,8 @@
import java.util.concurrent.ConcurrentHashMap;
/**
- * Represents a connection to a remote endpoint that carries voice traffic.
+ * 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
@@ -53,21 +54,52 @@
*/
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;
- /** Connection can currently be put on hold or unheld. */
+ /**
+ * 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. */
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 1e8ae88..d2e7a74 100644
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -41,8 +41,8 @@
import java.util.concurrent.ConcurrentHashMap;
/**
- * {@code ConnectionService} is an abstract service that should be implemented by any app which can
- * make phone calls and want those calls to be integrated into the built-in phone app.
+ * An abstract service that should be implemented by any apps which can make phone calls (VoIP or
+ * otherwise) and want those calls to be integrated into the built-in phone app.
* Once implemented, the {@code ConnectionService} needs two additional steps before it will be
* integrated into the phone app:
* <p>
@@ -62,7 +62,7 @@
* <br/>
* See {@link PhoneAccount} and {@link TelecomManager#registerPhoneAccount} for more information.
* <p>
- * Once registered and enabled by the user in the dialer settings, telecom will bind to a
+ * Once registered and enabled by the user in the phone app settings, telecom will bind to a
* {@code ConnectionService} implementation when it wants that {@code ConnectionService} to place
* a call or the service has indicated that is has an incoming call through
* {@link TelecomManager#addNewIncomingCall}. The {@code ConnectionService} can then expect a call
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index 0f8ac63..19c613d 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -248,7 +248,7 @@
}
/**
- * Obtains the current list of {@code Call}s to be displayed by this in-call experience.
+ * Obtains the current list of {@code Call}s to be displayed by this in-call service.
*
* @return A list of the relevant {@code Call}s.
*/
diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index a25d327..df6fa2e 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -412,7 +412,7 @@
* bit mask.
*
* @param capability The capabilities to check.
- * @return {@code True} if the phone account has the capability.
+ * @return {@code true} if the phone account has the capability.
*/
public boolean hasCapabilities(int capability) {
return (mCapabilities & capability) == capability;
@@ -455,9 +455,10 @@
}
/**
- * Indicates whether the user has enabled this phone account or not {@code PhoneAccounts}.
+ * Indicates whether the user has enabled this {@code PhoneAccount} or not. This value is only
+ * populated for {@code PhoneAccount}s returned by {@link TelecomManager#getPhoneAccount}.
*
- * @return The {@code true} if the account is enabled by the user, {@code false} otherwise.
+ * @return {@code true} if the account is enabled by the user, {@code false} otherwise.
*/
public boolean isEnabled() {
return mIsEnabled;
@@ -468,7 +469,7 @@
* scheme.
*
* @param uriScheme The URI scheme to check.
- * @return {@code True} if the {@code PhoneAccount} supports calls to/from addresses with the
+ * @return {@code true} if the {@code PhoneAccount} supports calls to/from addresses with the
* specified URI scheme.
*/
public boolean supportsUriScheme(String uriScheme) {
diff --git a/telecomm/java/android/telecom/RemoteConference.java b/telecomm/java/android/telecom/RemoteConference.java
index c2261c3..ae5cd46 100644
--- a/telecomm/java/android/telecom/RemoteConference.java
+++ b/telecomm/java/android/telecom/RemoteConference.java
@@ -32,25 +32,90 @@
import java.util.concurrent.CopyOnWriteArraySet;
/**
- * A conference provided to a {@link ConnectionService} by another {@code ConnectionService}
- * running in a different process.
+ * A conference provided to a {@link ConnectionService} by another {@code ConnectionService} through
+ * {@link ConnectionService#conferenceRemoteConnections}. Once created, a {@code RemoteConference}
+ * can be used to control the conference call or monitor changes through
+ * {@link RemoteConnection.Callback}.
*
* @see ConnectionService#onRemoteConferenceAdded
*/
public final class RemoteConference {
+ /**
+ * Callback base class for {@link RemoteConference}.
+ */
public abstract static class Callback {
+ /**
+ * Invoked when the state of this {@code RemoteConferece} has changed. See
+ * {@link #getState()}.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param oldState The previous state of the {@code RemoteConference}.
+ * @param newState The new state of the {@code RemoteConference}.
+ */
public void onStateChanged(RemoteConference conference, int oldState, int newState) {}
+
+ /**
+ * Invoked when this {@code RemoteConference} is disconnected.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param disconnectCause The ({@see DisconnectCause}) associated with this failed
+ * conference.
+ */
public void onDisconnected(RemoteConference conference, DisconnectCause disconnectCause) {}
+
+ /**
+ * Invoked when a {@link RemoteConnection} is added to the conference call.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param connection The {@link RemoteConnection} being added.
+ */
public void onConnectionAdded(RemoteConference conference, RemoteConnection connection) {}
+
+ /**
+ * Invoked when a {@link RemoteConnection} is removed from the conference call.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param connection The {@link RemoteConnection} being removed.
+ */
public void onConnectionRemoved(RemoteConference conference, RemoteConnection connection) {}
+
+ /**
+ * Indicates that the call capabilities of this {@code RemoteConference} have changed.
+ * See {@link #getConnectionCapabilities()}.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param connectionCapabilities The new capabilities of the {@code RemoteConference}.
+ */
public void onConnectionCapabilitiesChanged(
RemoteConference conference,
int connectionCapabilities) {}
+
+ /**
+ * Invoked when the set of {@link RemoteConnection}s which can be added to this conference
+ * call have changed.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param conferenceableConnections The list of conferenceable {@link RemoteConnection}s.
+ */
public void onConferenceableConnectionsChanged(
RemoteConference conference,
List<RemoteConnection> conferenceableConnections) {}
+
+ /**
+ * Indicates that this {@code RemoteConference} has been destroyed. No further requests
+ * should be made to the {@code RemoteConference}, and references to it should be cleared.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ */
public void onDestroyed(RemoteConference conference) {}
+
+ /**
+ * Handles changes to the {@code RemoteConference} extras.
+ *
+ * @param conference The {@code RemoteConference} invoking this method.
+ * @param extras The extras containing other information associated with the conference.
+ */
public void onExtrasChanged(RemoteConference conference, @Nullable Bundle extras) {}
}
diff --git a/telecomm/java/android/telecom/RemoteConnection.java b/telecomm/java/android/telecom/RemoteConnection.java
index 8f7b82f..f960959 100644
--- a/telecomm/java/android/telecom/RemoteConnection.java
+++ b/telecomm/java/android/telecom/RemoteConnection.java
@@ -45,6 +45,9 @@
*/
public final class RemoteConnection {
+ /**
+ * Callback base class for {@link RemoteConnection}.
+ */
public static abstract class Callback {
/**
* Invoked when the state of this {@code RemoteConnection} has changed. See
@@ -200,7 +203,7 @@
RemoteConference conference) {}
/**
- * Handles changes to the {@code RemoteConference} extras.
+ * Handles changes to the {@code RemoteConnection} extras.
*
* @param connection The {@code RemoteConnection} invoking this method.
* @param extras The extras containing other information associated with the connection.
diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java
index 11f206a..a30e1c0 100644
--- a/telecomm/java/android/telecom/TelecomManager.java
+++ b/telecomm/java/android/telecom/TelecomManager.java
@@ -67,11 +67,19 @@
public static final String ACTION_NEW_UNKNOWN_CALL = "android.telecom.action.NEW_UNKNOWN_CALL";
/**
- * The {@link android.content.Intent} action used to configure a
- * {@link android.telecom.ConnectionService}.
+ * An {@link android.content.Intent} action sent by the telecom framework to start a
+ * configuration dialog for a registered {@link PhoneAccount}. There is no default dialog
+ * and each app that registers a {@link PhoneAccount} should provide one if desired.
+ * <p>
+ * A user can access the list of enabled {@link android.telecom.PhoneAccount}s through the Phone
+ * app's settings menu. For each entry, the settings app will add a click action. When
+ * triggered, the click-action will start this intent along with the extra
+ * {@link #EXTRA_PHONE_ACCOUNT_HANDLE} to indicate the {@link PhoneAccount} to configure. If the
+ * {@link PhoneAccount} package does not register an {@link android.app.Activity} for this
+ * intent, then it will not be sent.
*/
- public static final String ACTION_CONNECTION_SERVICE_CONFIGURE =
- "android.telecom.action.CONNECTION_SERVICE_CONFIGURE";
+ public static final String ACTION_CONFIGURE_PHONE_ACCOUNT =
+ "android.telecom.action.CONFIGURE_PHONE_ACCOUNT";
/**
* The {@link android.content.Intent} action used to show the call accessibility settings page.