Clarify some UCE API docs
Adds some clarifications for how UCE operates
in Android 12.
Fixes: 188580687
Test: docs only change
Change-Id: I139455c286378ccfac876014656f8d3177bdba9d
diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index 579b33e..e332d3f 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -27,6 +27,7 @@
import android.os.Bundle;
import android.os.Parcel;
import android.os.Parcelable;
+import android.telephony.CarrierConfigManager;
import android.telephony.TelephonyManager;
import android.text.TextUtils;
@@ -283,10 +284,13 @@
* number relies on presence. Should only be set if the {@code PhoneAccount} also has
* {@link #CAPABILITY_VIDEO_CALLING}.
* <p>
- * When set, the {@link ConnectionService} is responsible for toggling the
+ * Note: As of Android 12, using the
* {@link android.provider.ContactsContract.Data#CARRIER_PRESENCE_VT_CAPABLE} bit on the
* {@link android.provider.ContactsContract.Data#CARRIER_PRESENCE} column to indicate whether
- * a contact's phone number supports video calling.
+ * a contact's phone number supports video calling has been deprecated and should only be used
+ * on devices where {@link CarrierConfigManager#KEY_USE_RCS_PRESENCE_BOOL} is set. On newer
+ * devices, applications must use {@link android.telephony.ims.RcsUceAdapter} instead to
+ * determine whether or not a contact's phone number supports carrier video calling.
* <p>
* See {@link #getCapabilities}
*/
diff --git a/telephony/java/android/telephony/CarrierConfigManager.java b/telephony/java/android/telephony/CarrierConfigManager.java
index 33a9a96..d08f777 100644
--- a/telephony/java/android/telephony/CarrierConfigManager.java
+++ b/telephony/java/android/telephony/CarrierConfigManager.java
@@ -38,6 +38,7 @@
import android.telephony.ims.ImsReasonInfo;
import android.telephony.ims.ImsRegistrationAttributes;
import android.telephony.ims.ImsSsData;
+import android.telephony.ims.RcsUceAdapter;
import android.telephony.ims.feature.MmTelFeature;
import android.telephony.ims.feature.RcsFeature;
@@ -4259,6 +4260,9 @@
* If this flag is disabled, the capabilities cache will not be refreshed internally at all
* and will only be updated if the cached capabilities are stale when an application
* requests them.
+ *
+ * @see RcsUceAdapter#isUceSettingEnabled() more information about this feature and how
+ * it is enabled by the user.
*/
public static final String KEY_RCS_BULK_CAPABILITY_EXCHANGE_BOOL =
KEY_PREFIX + "rcs_bulk_capability_exchange_bool";
diff --git a/telephony/java/android/telephony/ims/ImsRcsManager.java b/telephony/java/android/telephony/ims/ImsRcsManager.java
index 814ce18..3700026 100644
--- a/telephony/java/android/telephony/ims/ImsRcsManager.java
+++ b/telephony/java/android/telephony/ims/ImsRcsManager.java
@@ -56,7 +56,9 @@
/**
* Activity Action: Show the opt-in dialog for enabling or disabling RCS contact discovery
- * using User Capability Exchange (UCE).
+ * using User Capability Exchange (UCE), which enables a service that periodically shares the
+ * phone numbers of all of the contacts in the user's address book with the carrier to refresh
+ * the RCS capabilities associated with those contacts as the local cache becomes stale.
* <p>
* An application that depends on RCS contact discovery being enabled must send this intent
* using {@link Context#startActivity(Intent)} to ask the user to opt-in for contacts upload for
diff --git a/telephony/java/android/telephony/ims/RcsUceAdapter.java b/telephony/java/android/telephony/ims/RcsUceAdapter.java
index dd91026..7a1c092 100644
--- a/telephony/java/android/telephony/ims/RcsUceAdapter.java
+++ b/telephony/java/android/telephony/ims/RcsUceAdapter.java
@@ -28,10 +28,13 @@
import android.os.IBinder;
import android.os.RemoteException;
import android.os.ServiceSpecificException;
+import android.telephony.CarrierConfigManager;
+import android.telephony.SubscriptionManager;
import android.telephony.TelephonyFrameworkInitializer;
import android.telephony.ims.aidl.IImsRcsController;
import android.telephony.ims.aidl.IRcsUceControllerCallback;
import android.telephony.ims.aidl.IRcsUcePublishStateCallback;
+import android.telephony.ims.feature.RcsFeature;
import android.util.Log;
import java.lang.annotation.Retention;
@@ -417,7 +420,7 @@
* <p>
* After {@link CapabilitiesCallback#onComplete} or {@link CapabilitiesCallback#onError} has
* been called, the reference to this callback will be discarded on the service side.
- * @see #requestCapabilities(Executor, List, CapabilitiesCallback)
+ * @see #requestCapabilities(Collection, Executor, CapabilitiesCallback)
* @hide
*/
@SystemApi
@@ -464,10 +467,16 @@
}
/**
- * Request the User Capability Exchange capabilities for one or more contacts.
+ * Request the RCS capabilities for one or more contacts using RCS User Capability Exchange.
* <p>
- * This will return the cached capabilities of the contact and will not perform a capability
- * poll on the network unless there are contacts being queried with stale information.
+ * This API will first check a local cache for the requested numbers and return the cached
+ * RCS capabilities of each number if the cache exists and is not stale. If the cache for a
+ * number is stale or there is no cached information about the requested number, the device will
+ * then perform a query to the carrier's network to request the RCS capabilities of the
+ * requested numbers.
+ * <p>
+ * Depending on the number of requests being sent, this API may throttled internally as the
+ * operations are queued to be executed by the carrier's network.
* <p>
* Be sure to check the availability of this feature using
* {@link ImsRcsManager#isAvailable(int, int)} and ensuring
@@ -552,13 +561,15 @@
}
/**
- * Ignore the device cache and perform a capability discovery for one contact, also called
- * "availability fetch."
+ * Request the RCS capabilities for a phone number using User Capability Exchange.
* <p>
- * This will always perform a query to the network as long as requests are over the carrier
- * availability fetch throttling threshold. If too many network requests are sent too quickly,
- * #ERROR_TOO_MANY_REQUESTS will be returned.
- *
+ * Unlike {@link #requestCapabilities(Collection, Executor, CapabilitiesCallback)}, which caches
+ * the result received from the network for a certain amount of time and uses that cached result
+ * for subsequent requests for RCS capabilities of the same phone number, this API will always
+ * request the RCS capabilities of a contact from the carrier's network.
+ * <p>
+ * Depending on the number of requests, this API may throttled internally as the operations are
+ * queued to be executed by the carrier's network.
* <p>
* Be sure to check the availability of this feature using
* {@link ImsRcsManager#isAvailable(int, int)} and ensuring
@@ -680,7 +691,8 @@
* state updates for the subscription specified in {@link ImsManager@getRcsManager(subid)}.
* <p>
* Use {@link SubscriptionManager.OnSubscriptionsChangedListener} to listen to subscription
- * changed events and call {@link #unregisterPublishStateCallback} to clean up.
+ * changed events and call
+ * {@link #removeOnPublishStateChangedListener(OnPublishStateChangedListener)} to clean up.
* <p>
* The registered {@link OnPublishStateChangedListener} will also receive a callback when it is
* registered with the current publish state.
@@ -770,13 +782,23 @@
}
/**
- * The user’s setting for whether or not User Capability Exchange (UCE) is enabled for the
- * associated subscription.
+ * The setting for whether or not the user has opted in to the automatic refresh of the RCS
+ * capabilities associated with the contacts in the user's contact address book. By default,
+ * this setting is disabled and must be enabled after the user has seen the opt-in dialog shown
+ * by {@link ImsRcsManager#ACTION_SHOW_CAPABILITY_DISCOVERY_OPT_IN}.
+ * <p>
+ * If this feature is enabled, the device will periodically share the phone numbers of all of
+ * the contacts in the user's address book with the carrier to refresh the RCS capabilities
+ * cache associated with those contacts as the local cache becomes stale.
+ * <p>
+ * This setting will only enable this feature if
+ * {@link CarrierConfigManager.Ims#KEY_RCS_BULK_CAPABILITY_EXCHANGE_BOOL} is also enabled.
* <p>
* Note: This setting does not affect whether or not the device publishes its service
* capabilities if the subscription supports presence publication.
*
- * @return true if the user’s setting for UCE is enabled, false otherwise.
+ * @return true if the user has opted in for automatic refresh of the RCS capabilities of their
+ * contacts, false otherwise.
* @throws ImsException if the subscription associated with this instance of
* {@link RcsUceAdapter} is valid, but the ImsService associated with the subscription is not
* available. This can happen if the ImsService has crashed, for example, or if the subscription
@@ -802,18 +824,33 @@
}
/**
- * Change the user’s setting for whether or not UCE is enabled for the associated subscription.
+ * Change the user’s setting for whether or not the user has opted in to the automatic
+ * refresh of the RCS capabilities associated with the contacts in the user's contact address
+ * book. By default, this setting is disabled and must be enabled using this method after the
+ * user has seen the opt-in dialog shown by
+ * {@link ImsRcsManager#ACTION_SHOW_CAPABILITY_DISCOVERY_OPT_IN}.
* <p>
- * If an application Requires UCE, they will launch an Activity using the Intent
- * {@link ImsRcsManager#ACTION_SHOW_CAPABILITY_DISCOVERY_OPT_IN}, which will ask the user if
- * they wish to enable this feature. This setting should only be enabled after the user has
- * opted-in to capability exchange.
+ * If an application wishes to request that the user enable this feature, they must launch an
+ * Activity using the Intent {@link ImsRcsManager#ACTION_SHOW_CAPABILITY_DISCOVERY_OPT_IN},
+ * which will ask the user if they wish to enable this feature. This setting must only be
+ * enabled after the user has opted-in to this feature.
+ * <p>
+ * This must not affect the
+ * {@link #requestCapabilities(Collection, Executor, CapabilitiesCallback)} or
+ * {@link #requestAvailability(Uri, Executor, CapabilitiesCallback)} API,
+ * as those APIs are still required for per-contact RCS capability queries of phone numbers
+ * required for operations such as placing a Video Telephony call or starting an RCS chat
+ * session.
+ * <p>
+ * This setting will only enable this feature if
+ * {@link CarrierConfigManager.Ims#KEY_RCS_BULK_CAPABILITY_EXCHANGE_BOOL} is also enabled.
* <p>
* Note: This setting does not affect whether or not the device publishes its service
* capabilities if the subscription supports presence publication.
*
- * @param isEnabled the user's setting for whether or not they wish for User
- * Capability Exchange to be enabled.
+ * @param isEnabled true if the user has opted in for automatic refresh of the RCS capabilities
+ * of their contacts, or false if they have chosen to opt-out. By default this
+ * setting is disabled.
* @throws ImsException if the subscription associated with this instance of
* {@link RcsUceAdapter} is valid, but the ImsService associated with the subscription is not
* available. This can happen if the ImsService has crashed, for example, or if the subscription