From 913b325c8bf3766496480be0ea58192f47823876 Mon Sep 17 00:00:00 2001 From: Brad Ebinger Date: Thu, 8 Apr 2021 18:30:30 +0000 Subject: [PATCH] Rename closeDialog to cleanupSession The current name of SipDelegate[Connection]#closeDialog assumes there will only be one SIP dialog per SIP session and does not adequately cover the case where a SIP INVITE has forked and generated multiple dialogs for the same call-id. Instead, rename closeDialog to cleanupSession, which is more accurate and should be called after all SIP dialogs associated with the SIP session represented by the call-id have closed. Bug: 184858064 Test: atest CtsTelephonyTestCases Change-Id: I438dbc45dffbaf33e0cf36ddc61008fd8c18209c --- core/api/system-current.txt | 6 +++-- .../ims/DelegateRegistrationState.java | 8 +++---- .../telephony/ims/SipDelegateConnection.java | 24 ++++++++++++++++++- .../telephony/ims/aidl/ISipDelegate.aidl | 2 +- .../ims/aidl/SipDelegateAidlWrapper.java | 4 ++-- .../SipDelegateConnectionAidlWrapper.java | 4 ++-- .../telephony/ims/stub/SipDelegate.java | 24 ++++++++++++++++++- 7 files changed, 59 insertions(+), 13 deletions(-) diff --git a/core/api/system-current.txt b/core/api/system-current.txt index e6624cdb865a4..0ffeb98c12dcc 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -11884,7 +11884,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); @@ -12333,7 +12334,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); diff --git a/telephony/java/android/telephony/ims/DelegateRegistrationState.java b/telephony/java/android/telephony/ims/DelegateRegistrationState.java index fd206c1e803f7..c00c741a0d60d 100644 --- a/telephony/java/android/telephony/ims/DelegateRegistrationState.java +++ b/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. *

* 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. *

* 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. *

* 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; diff --git a/telephony/java/android/telephony/ims/SipDelegateConnection.java b/telephony/java/android/telephony/ims/SipDelegateConnection.java index 04a772cd873d6..d7a19bc0cb628 100644 --- a/telephony/java/android/telephony/ims/SipDelegateConnection.java +++ b/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. + *

+ * 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. + *

+ * 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 diff --git a/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl b/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl index ad75be439da82..ff1a8f03350e9 100644 --- a/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl +++ b/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); } diff --git a/telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java b/telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java index 5c9ec53d713be..6a98d80d6b9b2 100644 --- a/telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java +++ b/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); } diff --git a/telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java b/telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java index ad02fe55902f1..0abb49574a734 100644 --- a/telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java +++ b/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. } diff --git a/telephony/java/android/telephony/ims/stub/SipDelegate.java b/telephony/java/android/telephony/ims/stub/SipDelegate.java index b036b5e71125a..d5198a0aa25c8 100644 --- a/telephony/java/android/telephony/ims/stub/SipDelegate.java +++ b/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. + *

+ * 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.