Merge "Rename closeDialog to cleanupSession"
diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index db50f0b..d39c6e2 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -11890,7 +11890,8 @@
}
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 @@
}
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 fd206c1..c00c741 100644
--- a/telephony/java/android/telephony/ims/DelegateRegistrationState.java
+++ b/telephony/java/android/telephony/ims/DelegateRegistrationState.java
@@ -63,7 +63,7 @@
* 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 @@
* 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 @@
* 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 @@
* 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;
diff --git a/telephony/java/android/telephony/ims/SipDelegateConnection.java b/telephony/java/android/telephony/ims/SipDelegateConnection.java
index 04a772c..d7a19bc 100644
--- a/telephony/java/android/telephony/ims/SipDelegateConnection.java
+++ b/telephony/java/android/telephony/ims/SipDelegateConnection.java
@@ -74,8 +74,30 @@
* 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
diff --git a/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl b/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl
index ad75be4..ff1a8f0 100644
--- a/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl
+++ b/telephony/java/android/telephony/ims/aidl/ISipDelegate.aidl
@@ -26,5 +26,5 @@
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 5c9ec53..6a98d80 100644
--- a/telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java
+++ b/telephony/java/android/telephony/ims/aidl/SipDelegateAidlWrapper.java
@@ -79,11 +79,11 @@
}
@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 ad02fe5..0abb495 100644
--- a/telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java
+++ b/telephony/java/android/telephony/ims/aidl/SipDelegateConnectionAidlWrapper.java
@@ -200,13 +200,13 @@
}
@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 b036b5e..d5198a0 100644
--- a/telephony/java/android/telephony/ims/stub/SipDelegate.java
+++ b/telephony/java/android/telephony/ims/stub/SipDelegate.java
@@ -76,8 +76,30 @@
*
* @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.