Merge "Rename closeDialog to cleanupSession" am: 0a99b6c48b

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1670485

Change-Id: I4d7fe4a63ccb193e5ba103c4e07cd9d9342161d5

core/api/system-current.txt

@@ -11890,7 +11890,8 @@ package android.telephony.ims {
   }
 
   public interface SipDelegateConnection {
-    method public void closeDialog(@NonNull String);
+    method public default void cleanupSession(@NonNull String);
+    method @Deprecated public default void closeDialog(@NonNull String);
     method public void notifyMessageReceiveError(@NonNull String, int);
     method public void notifyMessageReceived(@NonNull String);
     method public void sendMessage(@NonNull android.telephony.ims.SipMessage, long);
@@ -12340,7 +12341,8 @@ package android.telephony.ims.stub {
   }
 
   public interface SipDelegate {
-    method public void closeDialog(@NonNull String);
+    method public default void cleanupSession(@NonNull String);
+    method @Deprecated public default void closeDialog(@NonNull String);
     method public void notifyMessageReceiveError(@NonNull String, int);
     method public void notifyMessageReceived(@NonNull String);
     method public void sendMessage(@NonNull android.telephony.ims.SipMessage, long);

telephony/java/android/telephony/ims/DelegateRegistrationState.java

@@ -63,7 +63,7 @@ public final class DelegateRegistrationState implements Parcelable {
      * This feature tag is being deregistered because the PDN that the IMS registration is on is
      *changing.
      * All open SIP dialogs need to be closed before the PDN change can proceed using
-     * {@link SipDelegateConnection#closeDialog(String)}.
+     * {@link SipDelegateConnection#cleanupSession(String)}.
      */
     public static final int DEREGISTERING_REASON_PDN_CHANGE = 3;
 
@@ -74,7 +74,7 @@ public final class DelegateRegistrationState implements Parcelable {
      * a user triggered hange, such as data being enabled/disabled.
      * <p>
      * All open SIP dialogs associated with the new deprovisioned feature tag need to be closed
-     * using {@link SipDelegateConnection#closeDialog(String)} before the IMS registration
+     * using {@link SipDelegateConnection#cleanupSession(String)} before the IMS registration
      * modification can proceed.
      */
     public static final int DEREGISTERING_REASON_PROVISIONING_CHANGE = 4;
@@ -84,7 +84,7 @@ public final class DelegateRegistrationState implements Parcelable {
      * needs to change its supported feature set.
      * <p>
      * All open SIP Dialogs associated with this feature tag must be  closed
-     * using {@link SipDelegateConnection#closeDialog(String)} before this operation can proceed.
+     * using {@link SipDelegateConnection#cleanupSession(String)} before this operation can proceed.
      */
     public static final int DEREGISTERING_REASON_FEATURE_TAGS_CHANGING = 5;
 
@@ -93,7 +93,7 @@ public final class DelegateRegistrationState implements Parcelable {
      * destroyed.
      * <p>
      * All open SIP Dialogs associated with this feature tag must be closed
-     * using {@link SipDelegateConnection#closeDialog(String)} before this operation can proceed.
+     * using {@link SipDelegateConnection#cleanupSession(String)} before this operation can proceed.
      */
     public static final int DEREGISTERING_REASON_DESTROY_PENDING = 6;
 

telephony/java/android/telephony/ims/SipDelegateConnection.java

@@ -74,8 +74,30 @@ public interface SipDelegateConnection {
      * closed.
      * @param callId The call-ID header value associated with the ongoing SIP Dialog that is
      *         closing.
+     * @deprecated closeDialog does not capture INVITE forking. Use {@link #cleanupSession} instead.
      */
-    void closeDialog(@NonNull String callId);
+    @Deprecated
+    default void closeDialog(@NonNull String callId) {
+        cleanupSession(callId);
+    }
+
+    /**
+     * The SIP session associated with the provided Call-ID is being closed and routing resources
+     * associated with the session are free to be released. Each SIP session may contain multiple
+     * dialogs due to SIP INVITE forking, so this method must be called after all SIP dialogs
+     * associated with the session has closed.
+     * <p>
+     * Calling this method is also mandatory for situations where the framework IMS stack is waiting
+     * for pending SIP sessions to be closed before it can perform a handover or apply a
+     * provisioning change. See {@link DelegateRegistrationState} for more information about
+     * the scenarios where this can occur.
+     * <p>
+     * This method will need to be called for each SIP session managed by this application when it
+     * is closed.
+     * @param callId The call-ID header value associated with the ongoing SIP Dialog that is
+     *         closing.
+     */
+    default void cleanupSession(@NonNull String callId) { }
 
     /**
      * Notify the SIP delegate that the SIP message has been received from

telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl

@@ -26,5 +26,5 @@ oneway interface ISipDelegate {
     void sendMessage(in SipMessage sipMessage, long configVersion);
     void notifyMessageReceived(in String viaTransactionId);
     void notifyMessageReceiveError(in String viaTransactionId, int reason);
-    void closeDialog(in String callId);
+    void cleanupSession(in String callId);
 }

telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java

@@ -79,11 +79,11 @@ public class SipDelegateAidlWrapper implements DelegateStateCallback, DelegateMe
         }
 
         @Override
-        public void closeDialog(String callId)  {
+        public void cleanupSession(String callId)  {
             SipDelegate d = mDelegate;
             final long token = Binder.clearCallingIdentity();
             try {
-                mExecutor.execute(() -> d.closeDialog(callId));
+                mExecutor.execute(() -> d.cleanupSession(callId));
             } finally {
                 Binder.restoreCallingIdentity(token);
             }

telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java

@@ -200,13 +200,13 @@ public class SipDelegateConnectionAidlWrapper implements SipDelegateConnection,
     }
 
     @Override
-    public void closeDialog(String callId) {
+    public void cleanupSession(String callId) {
         try {
             ISipDelegate conn = getSipDelegateBinder();
             if (conn == null) {
                 return;
             }
-            conn.closeDialog(callId);
+            conn.cleanupSession(callId);
         } catch (RemoteException e) {
             // Nothing to do here, app will eventually get remote death callback.
         }

telephony/java/android/telephony/ims/stub/SipDelegate.java

@@ -76,8 +76,30 @@ public interface SipDelegate {
      *
      * @param callId The call-ID header value associated with the ongoing SIP Dialog that the
      *         framework is requesting be closed.
+     * @deprecated This method does not take into account INVITE forking. Use
+     * {@link #cleanupSession(String)} instead.
      */
-    void closeDialog(@NonNull String callId);
+    @Deprecated
+    default void closeDialog(@NonNull String callId) { }
+
+    /**
+     * The remote IMS application has closed a SIP session and the routing resources associated
+     * with the SIP session using the provided Call-ID may now be cleaned up.
+     * <p>
+     * Typically, a SIP session will be considered closed when all associated dialogs receive a
+     * BYE request. After the session has been closed, the IMS application will call
+     * {@link SipDelegateConnection#cleanupSession(String)} to signal to the framework that
+     * resources can be released. In some cases, the framework will request that the ImsService
+     * close the session due to the open SIP session holding up an event such as applying a
+     * provisioning change or handing over to another transport type. See
+     * {@link DelegateRegistrationState}.
+     *
+     * @param callId The call-ID header value associated with the ongoing SIP Session that the
+     *         framework is requesting be cleaned up.
+     */
+    default void cleanupSession(@NonNull String callId) {
+        closeDialog(callId);
+    }
 
     /**
      * The remote application has received the SIP message and is processing it.