Update PhoneAccountHandle API docs.
Ensure docs clearly state that handle id should not contain PII.
Test: Docs only change.
Fixes: 192673156
Change-Id: I4a612876fa5e2aac2159928b4c6cfde253d7395a
diff --git a/telecomm/java/android/telecom/PhoneAccountHandle.java b/telecomm/java/android/telecom/PhoneAccountHandle.java
index e1bcb5f..e3485de 100644
--- a/telecomm/java/android/telecom/PhoneAccountHandle.java
+++ b/telecomm/java/android/telecom/PhoneAccountHandle.java
@@ -34,7 +34,10 @@
* <ul>
* <li>The component name of the associated connection service.</li>
* <li>A string identifier that is unique across {@code PhoneAccountHandle}s with the same
- * component name.</li>
+ * component name. Apps registering {@link PhoneAccountHandle}s should ensure that the
+ * {@link #getId()} provided does not expose personally identifying information. A
+ * {@link ConnectionService} should use an opaque token as the {@link PhoneAccountHandle}
+ * identifier.</li>
* </ul>
*
* Note: This Class requires a non-null {@link ComponentName} and {@link UserHandle} to operate
@@ -49,12 +52,35 @@
private final String mId;
private final UserHandle mUserHandle;
+ /**
+ * Creates a new {@link PhoneAccountHandle}.
+ *
+ * @param componentName The {@link ComponentName} of the {@link ConnectionService} which
+ * services this {@link PhoneAccountHandle}.
+ * @param id A string identifier that is unique across {@code PhoneAccountHandle}s with the same
+ * component name. Apps registering {@link PhoneAccountHandle}s should ensure that the
+ * ID provided does not expose personally identifying information. A
+ * {@link ConnectionService} should use an opaque token as the
+ * {@link PhoneAccountHandle} identifier.
+ */
public PhoneAccountHandle(
@NonNull ComponentName componentName,
@NonNull String id) {
this(componentName, id, Process.myUserHandle());
}
+ /**
+ * Creates a new {@link PhoneAccountHandle}.
+ *
+ * @param componentName The {@link ComponentName} of the {@link ConnectionService} which
+ * services this {@link PhoneAccountHandle}.
+ * @param id A string identifier that is unique across {@code PhoneAccountHandle}s with the same
+ * component name. Apps registering {@link PhoneAccountHandle}s should ensure that the
+ * ID provided does not expose personally identifying information. A
+ * {@link ConnectionService} should use an opaque token as the
+ * {@link PhoneAccountHandle} identifier.
+ * @param userHandle The {@link UserHandle} associated with this {@link PhoneAccountHandle}.
+ */
public PhoneAccountHandle(
@NonNull ComponentName componentName,
@NonNull String id,
@@ -80,17 +106,17 @@
* others supported by the connection service that created it.
* <p>
* A connection service 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.
- *
+ * their users' relationship with their service, across many Android devices. The identifier
+ * should be a stable opaque token which uniquely identifies the user within the 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.
+ * <p>
* Important: A non-unique identifier could cause non-deterministic call-log backup/restore
* behavior.
*
- * @return A service-specific unique identifier for this {@code PhoneAccountHandle}.
+ * @return A service-specific unique opaque identifier for this {@code PhoneAccountHandle}.
*/
public String getId() {
return mId;
@@ -157,7 +183,8 @@
}
}
- public static final @android.annotation.NonNull Creator<PhoneAccountHandle> CREATOR = new Creator<PhoneAccountHandle>() {
+ public static final @android.annotation.NonNull Creator<PhoneAccountHandle> CREATOR =
+ new Creator<PhoneAccountHandle>() {
@Override
public PhoneAccountHandle createFromParcel(Parcel in) {
return new PhoneAccountHandle(in);