Final structural tweaks to Telecomm API (1/8)
Bug: 16416927
Bug: 16494880
Change-Id: I45fbe287c410cbb5e1b985f320b862d732811f43
diff --git a/telecomm/java/android/telecomm/PhoneAccountHandle.java b/telecomm/java/android/telecomm/PhoneAccountHandle.java
index f14766c..04cd2b0 100644
--- a/telecomm/java/android/telecomm/PhoneAccountHandle.java
+++ b/telecomm/java/android/telecomm/PhoneAccountHandle.java
@@ -23,8 +23,7 @@
import java.util.Objects;
/**
- * Represents a distinct account, line of service or call placement method that
- * the system can use to place phone calls.
+ * The unique identifier for a {@link PhoneAccount}.
*/
public class PhoneAccountHandle implements Parcelable {
private ComponentName mComponentName;
@@ -48,10 +47,18 @@
}
/**
- * A unique identifier for this {@code PhoneAccountHandle}, generated by and meaningful to the
- * {@link android.telecomm.ConnectionService} that created it.
+ * A string that uniquely distinguishes this particular {@code PhoneAccountHandle} from all the
+ * others supported by the {@link ConnectionService} that created it.
+ * <p>
+ * A {@code ConnectionService} must select identifiers that are stable for the lifetime of
+ * their users' relationship with their service, across many Android devices. For example, a
+ * good set of identifiers might be the email addresses with which with users registered for
+ * their accounts with a particular service. Depending on how a service chooses to operate,
+ * a bad set of identifiers might be an increasing series of integers
+ * ({@code 0}, {@code 1}, {@code 2}, ...) that are generated locally on each phone and could
+ * collide with values generated on other phones or after a data wipe of a given phone.
*
- * @return A unique identifier for this {@code PhoneAccountHandle}.
+ * @return A service-specific unique identifier for this {@code PhoneAccountHandle}.
*/
public String getId() {
return mId;