From a4c198c413055af93cf10183c3649ba3fa2b2e67 Mon Sep 17 00:00:00 2001 From: Brad Ebinger Date: Thu, 12 Jan 2023 16:22:21 -0800 Subject: [PATCH] Mark older CapabilitiesCallback APIs as default - Mark the existing RcsUceAdapter.CapabilitiesCallback APIs as default. Otherwise, there is no way for apps to stop implementing the existing APIs in favor of new APIs that include SipDetails. - Not all apps actually require SipDetails, so we can keep the old versions of the methods without deprecation Bug: b/265170620 Test: atest CtsTelephonyTestCases:RcsUceAdapterTest Change-Id: I8783f54f9e92d0484e6064f4cb16473a8edd41fe --- core/api/system-current.txt | 4 +- .../android/telephony/ims/RcsUceAdapter.java | 61 +++++++++++++------ 2 files changed, 43 insertions(+), 22 deletions(-) diff --git a/core/api/system-current.txt b/core/api/system-current.txt index dd962cd11660b..1b4d14410bf0c 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -15712,9 +15712,9 @@ package android.telephony.ims { public static interface RcsUceAdapter.CapabilitiesCallback { method public void onCapabilitiesReceived(@NonNull java.util.List); - method @Deprecated public void onComplete(); + method public default void onComplete(); method public default void onComplete(@Nullable android.telephony.ims.SipDetails); - method @Deprecated public void onError(int, long); + method public default void onError(int, long); method public default void onError(int, long, @Nullable android.telephony.ims.SipDetails); } diff --git a/telephony/java/android/telephony/ims/RcsUceAdapter.java b/telephony/java/android/telephony/ims/RcsUceAdapter.java index b49181e7367b4..3bb9be0252cde 100644 --- a/telephony/java/android/telephony/ims/RcsUceAdapter.java +++ b/telephony/java/android/telephony/ims/RcsUceAdapter.java @@ -447,12 +447,12 @@ public class RcsUceAdapter { /** * 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. + * capabilities are fetched from multiple sources, both cached on the device and on the network. *

* 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. + * 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. @@ -463,22 +463,29 @@ public class RcsUceAdapter { public interface CapabilitiesCallback { /** - * Notify this application that the pending capability request has returned successfully - * for one or more of the requested contacts. + * The pending capability request has completed successfully for one or more of the + * requested contacts. + * This may be called one or more times before the request is fully completed, as + * capabilities may need to be fetched from multiple sources both on device and on the + * network. Once the capabilities of all the requested contacts have been received, + * {@link #onComplete()} will be called. If there was an error during the capability + * exchange process, {@link #onError(int, long)} will be called instead. * @param contactCapabilities List of capabilities associated with each contact requested. */ void onCapabilitiesReceived(@NonNull List contactCapabilities); /** - * The pending request has completed successfully due to all requested contacts information - * being delivered. The callback {@link #onCapabilitiesReceived(List)} - * for each contacts is required to be called before {@link #onComplete} is called. + * Called when the pending request has completed successfully due to all requested contacts + * information being delivered. The callback {@link #onCapabilitiesReceived(List)} will be + * called one or more times and will contain the contacts in the request that the device has + * received capabilities for. * - * @deprecated Replaced by {@link #onComplete(SipDetails)}, deprecated for - * SIP information. + * @see #onComplete(SipDetails) onComplete(SipDetails) provides more information related to + * the underlying SIP transaction used to perform the capabilities exchange. Either this + * method or the alternate method should be implemented to determine when the request has + * completed successfully. */ - @Deprecated - void onComplete(); + default void onComplete() {} /** * The pending request has resulted in an error and may need to be retried, depending on the @@ -487,18 +494,26 @@ public class RcsUceAdapter { * @param retryIntervalMillis The time in milliseconds the requesting application should * wait before retrying, if non-zero. * - * @deprecated Replaced by {@link #onError(int, long, SipDetails)}, deprecated for - * SIP information. + * @see #onError(int, long, SipDetails) onError(int, long, SipDetails) provides more + * information related to the underlying SIP transaction that resulted in an error. Either + * this method or the alternative method should be implemented to determine when the + * request has completed with an error. */ - @Deprecated - void onError(@ErrorCode int errorCode, long retryIntervalMillis); + default void onError(@ErrorCode int errorCode, long retryIntervalMillis) {} /** - * The pending request has completed successfully due to all requested contacts information - * being delivered. The callback {@link #onCapabilitiesReceived(List)} - * for each contacts is required to be called before {@link #onComplete} is called. + * Called when the pending request has completed successfully due to all requested contacts + * information being delivered. The callback {@link #onCapabilitiesReceived(List)} will be + * called one or more times and will contain the contacts in the request that the device has + * received capabilities for. * - * @param details The SIP information related to this request. + * This method contains more information about the underlying SIP transaction if it exists. + * If this information is not needed, {@link #onComplete()} can be implemented + * instead. + * + * @param details The SIP information related to this request if the device supports + * supplying this information. This parameter will be {@code null} if this + * information is not available. */ default void onComplete(@Nullable SipDetails details) { onComplete(); @@ -507,10 +522,16 @@ public class RcsUceAdapter { /** * The pending request has resulted in an error and may need to be retried, depending on the * error code. + * + * This method contains more information about the underlying SIP transaction if it exists. + * If this information is not needed, {@link #onError(int, long)} can be implemented + * instead. * @param errorCode The reason for the framework being unable to process the request. * @param retryIntervalMillis The time in milliseconds the requesting application should * wait before retrying, if non-zero. - * @param details The SIP information related to this request. + * @param details The SIP information related to this request if the device supports + * supplying this information. This parameter will be {@code null} if this + * information is not available. */ default void onError(@ErrorCode int errorCode, long retryIntervalMillis, @Nullable SipDetails details) {