drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify some UCE API docs

Browse Source 
Adds some clarifications for how UCE operates
in Android 12.

Fixes: 188580687
Test: docs only change
Change-Id: I139455c286378ccfac876014656f8d3177bdba9d
This commit is contained in:
Brad Ebinger 2021-05-14 01:53:56 +00:00
parent 211d685267
commit 722cacf24d
4 changed files with 71 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
telecomm/java/android/telecom/PhoneAccount.java
View File

@ -27,6 +27,7 @@ import android.net.Uri;
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 @@ public final class PhoneAccount implements Parcelable {
* 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}
*/

4
telephony/java/android/telephony/CarrierConfigManager.java
View File

@ -38,6 +38,7 @@ import android.telephony.gba.UaSecurityProtocolIdentifier;
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 @@ public class CarrierConfigManager {
* 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";

4
telephony/java/android/telephony/ims/ImsRcsManager.java
View File

@ -56,7 +56,9 @@ public class ImsRcsManager {
/**
* 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

79
telephony/java/android/telephony/ims/RcsUceAdapter.java
View File

@ -28,10 +28,13 @@ import android.os.Binder;
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 @@ public class RcsUceAdapter {
* <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 @@ public class RcsUceAdapter {
}
/**
* 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 @@ public class RcsUceAdapter {
}
/**
* 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 @@ public class RcsUceAdapter {
* 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 @@ public class RcsUceAdapter {
}
/**
* 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 @@ public class RcsUceAdapter {
}
/**
* 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