* Implementations create a custom subclass of {@code Connection} and return it to the framework * as the return value of @@ -53,21 +54,52 @@ import java.util.concurrent.ConcurrentHashMap; */ 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 1e8ae8802d231..d2e7a74977e02 100644 --- a/telecomm/java/android/telecom/ConnectionService.java +++ b/telecomm/java/android/telecom/ConnectionService.java @@ -41,8 +41,8 @@ import java.util.UUID; 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: *
@@ -62,7 +62,7 @@ import java.util.concurrent.ConcurrentHashMap;
*
* See {@link PhoneAccount} and {@link TelecomManager#registerPhoneAccount} for more information.
*
- * 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 0f8ac632a876b..19c613d3104db 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -248,7 +248,7 @@ public abstract class InCallService extends Service {
}
/**
- * 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 a25d327baf545..df6fa2e1b391c 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -412,7 +412,7 @@ public final class PhoneAccount implements Parcelable {
* 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 @@ public final class PhoneAccount implements Parcelable {
}
/**
- * 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 @@ public final class PhoneAccount implements Parcelable {
* 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 c2261c37e13de..ae5cd464d72c1 100644
--- a/telecomm/java/android/telecom/RemoteConference.java
+++ b/telecomm/java/android/telecom/RemoteConference.java
@@ -32,25 +32,90 @@ import java.util.concurrent.CopyOnWriteArrayList;
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
+ * 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.