* Device shall retry with exponential back-off. * @hide */ @SystemApi public static final int PUBLISH_STATE_OTHER_ERROR = 6; /**@hide*/ @Retention(RetentionPolicy.SOURCE) @IntDef(prefix = "PUBLISH_STATE_", value = { PUBLISH_STATE_OK, PUBLISH_STATE_NOT_PUBLISHED, PUBLISH_STATE_VOICE_PROVISION_ERROR, PUBLISH_STATE_RCS_PROVISION_ERROR, PUBLISH_STATE_REQUEST_TIMEOUT, PUBLISH_STATE_OTHER_ERROR }) public @interface PublishState {} /** * An application can use {@link #addOnPublishStateChangedListener} to register a * {@link OnPublishStateChangedListener ), which will notify the user when the publish state to * the network changes. * @hide */ @SystemApi public interface OnPublishStateChangedListener { /** * Notifies the callback when the publish state has changed. * @param publishState The latest update to the publish state. */ void onPublishStateChange(@PublishState int publishState); } /** * An application can use {@link #addOnPublishStateChangedListener} to register a * {@link OnPublishStateChangedListener ), which will notify the user when the publish state to * the network changes. * @hide */ public static class PublishStateCallbackAdapter { private static class PublishStateBinder extends IRcsUcePublishStateCallback.Stub { private final OnPublishStateChangedListener mPublishStateChangeListener; private final Executor mExecutor; PublishStateBinder(Executor executor, OnPublishStateChangedListener listener) { mExecutor = executor; mPublishStateChangeListener = listener; } @Override public void onPublishStateChanged(int publishState) { if (mPublishStateChangeListener == null) return; final long callingIdentity = Binder.clearCallingIdentity(); try { mExecutor.execute(() -> mPublishStateChangeListener.onPublishStateChange(publishState)); } finally { restoreCallingIdentity(callingIdentity); } } } private final PublishStateBinder mBinder; public PublishStateCallbackAdapter(@NonNull Executor executor, @NonNull OnPublishStateChangedListener listener) { mBinder = new PublishStateBinder(executor, listener); } /**@hide*/ public final IRcsUcePublishStateCallback getBinder() { return mBinder; } } /** * A callback for the response to a UCE request. The method * {@link CapabilitiesCallback#onCapabilitiesReceived} will be called zero or more times as the * capabilities are received for each requested contact. *
* This request will take a varying amount of time depending on if the contacts requested are * cached or if it requires a network query. The timeout time of these requests can vary * depending on the network, however in poor cases it could take up to a minute for a request * to timeout. In that time only a subset of capabilities may have been retrieved. *
* 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(Collection, Executor, CapabilitiesCallback)
* @hide
*/
@SystemApi
public interface CapabilitiesCallback {
/**
* Notify this application that the pending capability request has returned successfully
* for one or more of the requested contacts.
* @param contactCapabilities List of capabilities associated with each contact requested.
*/
void onCapabilitiesReceived(@NonNull List
* 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.
*
* 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.
*
* Be sure to check the availability of this feature using
* {@link ImsRcsManager#isAvailable(int, int)} and ensuring
* {@link RcsFeature.RcsImsCapabilities#CAPABILITY_TYPE_OPTIONS_UCE} or
* {@link RcsFeature.RcsImsCapabilities#CAPABILITY_TYPE_PRESENCE_UCE} is enabled or else
* this operation will fail with {@link #ERROR_NOT_AVAILABLE} or {@link #ERROR_NOT_ENABLED}.
*
* @param contactNumbers A list of numbers that the capabilities are being requested for.
* @param executor The executor that will be used when the request is completed and the
* {@link CapabilitiesCallback} is called.
* @param c A one-time callback for when the request for capabilities completes or there is an
* error processing the request.
* @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
* becomes inactive. See {@link ImsException#getCode()} for more information on the error codes.
* @hide
*/
@SystemApi
@RequiresPermission(allOf = {Manifest.permission.ACCESS_RCS_USER_CAPABILITY_EXCHANGE,
Manifest.permission.READ_CONTACTS})
public void requestCapabilities(@NonNull Collection
* 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.
*
* Depending on the number of requests, this API may throttled internally as the operations are
* queued to be executed by the carrier's network.
*
* Be sure to check the availability of this feature using
* {@link ImsRcsManager#isAvailable(int, int)} and ensuring
* {@link RcsFeature.RcsImsCapabilities#CAPABILITY_TYPE_OPTIONS_UCE} or
* {@link RcsFeature.RcsImsCapabilities#CAPABILITY_TYPE_PRESENCE_UCE} is
* enabled or else this operation will fail with
* {@link #ERROR_NOT_AVAILABLE} or {@link #ERROR_NOT_ENABLED}.
*
* @param contactNumber The contact of the capabilities is being requested for.
* @param executor The executor that will be used when the request is completed and the
* {@link CapabilitiesCallback} is called.
* @param c A one-time callback for when the request for capabilities completes or there is
* an error processing the request.
* @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
* becomes inactive. See {@link ImsException#getCode()} for more information on the error codes.
* @hide
*/
@SystemApi
@RequiresPermission(allOf = {Manifest.permission.ACCESS_RCS_USER_CAPABILITY_EXCHANGE,
Manifest.permission.READ_CONTACTS})
public void requestAvailability(@NonNull Uri contactNumber,
@NonNull @CallbackExecutor Executor executor,
@NonNull CapabilitiesCallback c) throws ImsException {
if (executor == null) {
throw new IllegalArgumentException("Must include a non-null Executor.");
}
if (contactNumber == null) {
throw new IllegalArgumentException("Must include non-null contact number.");
}
if (c == null) {
throw new IllegalArgumentException("Must include a non-null CapabilitiesCallback.");
}
IImsRcsController imsRcsController = getIImsRcsController();
if (imsRcsController == null) {
Log.e(TAG, "requestAvailability: IImsRcsController is null");
throw new ImsException("Cannot find remote IMS service",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
IRcsUceControllerCallback internalCallback = new IRcsUceControllerCallback.Stub() {
@Override
public void onCapabilitiesReceived(List
* Use {@link SubscriptionManager.OnSubscriptionsChangedListener} to listen to subscription
* changed events and call
* {@link #removeOnPublishStateChangedListener(OnPublishStateChangedListener)} to clean up.
*
* The registered {@link OnPublishStateChangedListener} will also receive a callback when it is
* registered with the current publish state.
*
* @param executor The executor the listener callback events should be run on.
* @param listener The {@link OnPublishStateChangedListener} to be added.
* @throws ImsException if the subscription associated with this callback is valid, but
* the {@link ImsService} associated with the subscription is not available. This can happen if
* the service crashed, for example. See {@link ImsException#getCode()} for a more detailed
* reason.
* @hide
*/
@SystemApi
@RequiresPermission(Manifest.permission.READ_PRIVILEGED_PHONE_STATE)
public void addOnPublishStateChangedListener(@NonNull @CallbackExecutor Executor executor,
@NonNull OnPublishStateChangedListener listener) throws ImsException {
if (executor == null) {
throw new IllegalArgumentException("Must include a non-null Executor.");
}
if (listener == null) {
throw new IllegalArgumentException(
"Must include a non-null OnPublishStateChangedListener.");
}
IImsRcsController imsRcsController = getIImsRcsController();
if (imsRcsController == null) {
Log.e(TAG, "addOnPublishStateChangedListener : IImsRcsController is null");
throw new ImsException("Cannot find remote IMS service",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
PublishStateCallbackAdapter stateCallback = addPublishStateCallback(executor, listener);
try {
imsRcsController.registerUcePublishStateCallback(mSubId, stateCallback.getBinder());
} catch (ServiceSpecificException e) {
throw new ImsException(e.getMessage(), e.errorCode);
} catch (RemoteException e) {
Log.e(TAG, "Error calling IImsRcsController#registerUcePublishStateCallback", e);
throw new ImsException("Remote IMS Service is not available",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
}
/**
* Removes an existing {@link OnPublishStateChangedListener}.
*
* When the subscription associated with this callback is removed
* (SIM removed, ESIM swap,etc...), this callback will automatically be removed. If this method
* is called for an inactive subscription, it will result in a no-op.
*
* @param listener The callback to be unregistered.
* @throws ImsException if the subscription associated with this callback is valid, but
* the {@link ImsService} associated with the subscription is not available. This can happen if
* the service crashed, for example. See {@link ImsException#getCode()} for a more detailed
* reason.
* @hide
*/
@SystemApi
@RequiresPermission(Manifest.permission.READ_PRIVILEGED_PHONE_STATE)
public void removeOnPublishStateChangedListener(
@NonNull OnPublishStateChangedListener listener) throws ImsException {
if (listener == null) {
throw new IllegalArgumentException(
"Must include a non-null OnPublishStateChangedListener.");
}
IImsRcsController imsRcsController = getIImsRcsController();
if (imsRcsController == null) {
Log.e(TAG, "removeOnPublishStateChangedListener: IImsRcsController is null");
throw new ImsException("Cannot find remote IMS service",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
PublishStateCallbackAdapter callback = removePublishStateCallback(listener);
if (callback == null) {
return;
}
try {
imsRcsController.unregisterUcePublishStateCallback(mSubId, callback.getBinder());
} catch (android.os.ServiceSpecificException e) {
throw new ImsException(e.getMessage(), e.errorCode);
} catch (RemoteException e) {
Log.e(TAG, "Error calling IImsRcsController#unregisterUcePublishStateCallback", e);
throw new ImsException("Remote IMS Service is not available",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
}
/**
* 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}.
*
* 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.
*
* This setting will only enable this feature if
* {@link CarrierConfigManager.Ims#KEY_RCS_BULK_CAPABILITY_EXCHANGE_BOOL} is also enabled.
*
* 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 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
* becomes inactive. See {@link ImsException#getCode()} for more information on the error codes.
*/
@RequiresPermission(Manifest.permission.READ_PHONE_STATE)
public boolean isUceSettingEnabled() throws ImsException {
IImsRcsController imsRcsController = getIImsRcsController();
if (imsRcsController == null) {
Log.e(TAG, "isUceSettingEnabled: IImsRcsController is null");
throw new ImsException("Can not find remote IMS service",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
try {
// Telephony.SimInfo#IMS_RCS_UCE_ENABLED can also be used to listen to changes to this.
return imsRcsController.isUceSettingEnabled(mSubId, mContext.getOpPackageName(),
mContext.getAttributionTag());
} catch (RemoteException e) {
Log.e(TAG, "Error calling IImsRcsController#isUceSettingEnabled", e);
throw new ImsException("Remote IMS Service is not available",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
}
/**
* 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}.
*
* 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.
*
* 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.
*
* This setting will only enable this feature if
* {@link CarrierConfigManager.Ims#KEY_RCS_BULK_CAPABILITY_EXCHANGE_BOOL} is also enabled.
*
* Note: This setting does not affect whether or not the device publishes its service
* capabilities if the subscription supports presence publication.
*
* @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
* becomes inactive. See {@link ImsException#getCode()} for more information on the error codes.
* @hide
*/
@SystemApi
@RequiresPermission(Manifest.permission.MODIFY_PHONE_STATE)
public void setUceSettingEnabled(boolean isEnabled) throws ImsException {
IImsRcsController imsRcsController = getIImsRcsController();
if (imsRcsController == null) {
Log.e(TAG, "setUceSettingEnabled: IImsRcsController is null");
throw new ImsException("Can not find remote IMS service",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
try {
imsRcsController.setUceSettingEnabled(mSubId, isEnabled);
} catch (RemoteException e) {
Log.e(TAG, "Error calling IImsRcsController#setUceSettingEnabled", e);
throw new ImsException("Remote IMS Service is not available",
ImsException.CODE_ERROR_SERVICE_UNAVAILABLE);
}
}
/**
* Add the {@link OnPublishStateChangedListener} to collection for tracking.
* @param executor The executor that will be used when the publish state is changed and the
* {@link OnPublishStateChangedListener} is called.
* @param listener The {@link OnPublishStateChangedListener} to call the publish state changed.
* @return The {@link PublishStateCallbackAdapter} to wrapper the
* {@link OnPublishStateChangedListener}
*/
private PublishStateCallbackAdapter addPublishStateCallback(@NonNull Executor executor,
@NonNull OnPublishStateChangedListener listener) {
PublishStateCallbackAdapter adapter = new PublishStateCallbackAdapter(executor, listener);
synchronized (mPublishStateCallbacks) {
mPublishStateCallbacks.put(listener, adapter);
}
return adapter;
}
/**
* Remove the existing {@link OnPublishStateChangedListener}.
* @param listener The {@link OnPublishStateChangedListener} to remove from the collection.
* @return The wrapper class {@link PublishStateCallbackAdapter} associated with the
* {@link OnPublishStateChangedListener}.
*/
private PublishStateCallbackAdapter removePublishStateCallback(
@NonNull OnPublishStateChangedListener listener) {
synchronized (mPublishStateCallbacks) {
return mPublishStateCallbacks.remove(listener);
}
}
private IImsRcsController getIImsRcsController() {
IBinder binder = TelephonyFrameworkInitializer
.getTelephonyServiceManager()
.getTelephonyImsServiceRegisterer()
.get();
return IImsRcsController.Stub.asInterface(binder);
}
}