From 9255332a479eeb0f28929c1b6d946e3cbbc072dd Mon Sep 17 00:00:00 2001
From: Andrey Volk <andywolk@gmail.com>
Date: Thu, 14 Sep 2023 22:14:16 +0300
Subject: [PATCH] Add new nua_handle_destroy_user() API.

---
 libsofia-sip-ua/nua/nua.c           | 30 +++++++++++++++++++++++++++++
 libsofia-sip-ua/nua/nua_common.c    |  1 +
 libsofia-sip-ua/nua/nua_stack.c     |  3 +++
 libsofia-sip-ua/nua/sofia-sip/nua.h |  6 +++++-
 4 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/libsofia-sip-ua/nua/nua.c b/libsofia-sip-ua/nua/nua.c
index 9a6c3b03..c0026c81 100644
--- a/libsofia-sip-ua/nua/nua.c
+++ b/libsofia-sip-ua/nua/nua.c
@@ -925,6 +925,36 @@ void nua_handle_destroy(nua_handle_t *nh)
   }
 }
 
+/** Attempt to destroy a handle indirectly.
+ *
+ * Does not destroy the handle directly but forwards the nua_r_destroy_user event
+ * to the application so it could call nua_handle_destroy() from there.
+ *
+ * @param nh              Pointer to operation handle
+ *
+ * @return
+ *    nothing
+ *
+ * @par Related Tags:
+ *    none
+ *
+ * @par Events:
+ *    none
+ *
+ * * @since New in @VERSION_1_13_17.
+ *
+ * @sa nua_handle_destroy(), nua_handle(), nua_handle_bind(), nua_handle_ref(), nua_handle_unref(),
+ * nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_bye().
+ */
+void nua_handle_destroy_user(nua_handle_t *nh)
+{
+    enter;
+
+    if (NH_IS_VALID(nh)) {
+        nua_signal(nh->nh_nua, nh, NULL, nua_r_destroy_user, 0, NULL, TAG_END());
+    }
+}
+
 /* ---------------------------------------------------------------------- */
 
 struct nua_stack_handle_make_replaces_args {
diff --git a/libsofia-sip-ua/nua/nua_common.c b/libsofia-sip-ua/nua/nua_common.c
index c340f148..1ad64342 100644
--- a/libsofia-sip-ua/nua/nua_common.c
+++ b/libsofia-sip-ua/nua/nua_common.c
@@ -378,6 +378,7 @@ char const *nua_event_name(nua_event_t event)
   case nua_r_ack: return "nua_r_ack";
   case nua_r_handle_unref: return "nua_r_handle_unref";
   case nua_r_unref: return "nua_r_unref";
+  case nua_r_destroy_user: return "nua_r_destroy_user";
   default: return "NUA_UNKNOWN";
   }
 }
diff --git a/libsofia-sip-ua/nua/nua_stack.c b/libsofia-sip-ua/nua/nua_stack.c
index 2e4dacba..a5d26554 100644
--- a/libsofia-sip-ua/nua/nua_stack.c
+++ b/libsofia-sip-ua/nua/nua_stack.c
@@ -690,6 +690,9 @@ void nua_stack_signal(nua_t *nua, su_msg_r msg, nua_ee_data_t *ee)
 		  su_msg_destroy(nua->nua_signal);
 	  }
     return;
+  case nua_r_destroy_user:
+    nua_stack_event(nh->nh_nua, nh, NULL, nua_r_destroy_user, 0, NULL, NULL);
+    break;
   case nua_r_unref:
     nua_unref(nua);
     break;
diff --git a/libsofia-sip-ua/nua/sofia-sip/nua.h b/libsofia-sip-ua/nua/sofia-sip/nua.h
index de68d624..46dea369 100644
--- a/libsofia-sip-ua/nua/sofia-sip/nua.h
+++ b/libsofia-sip-ua/nua/sofia-sip/nua.h
@@ -161,7 +161,8 @@ typedef enum nua_event_e {
   nua_i_register,		/**< Incoming REGISTER. @NEW_1_12_4. */
   nua_r_unref,			/** Calls nua_unref() from dispatcher @NEW_1_13_3 */
   nua_r_handle_unref,	/** Calls nua_handle_unref() from dispatcher @NEW_1_13_3 */
-  nua_r_nta_agent_resolver_clean_dns_cache /** Calls nua_resolver_clean_dns_cache() from dispatcher @NEW_1_13_12 */
+  nua_r_nta_agent_resolver_clean_dns_cache, /** Calls nua_resolver_clean_dns_cache() from dispatcher @NEW_1_13_12 */
+  nua_r_destroy_user    /** Requests dispatcher to forward the event to the app's callback @NEW_1_13_17 */
 } nua_event_t;
 
 typedef struct event_s {
@@ -219,6 +220,9 @@ SOFIAPUBFUN nua_handle_t *nua_handle(nua_t *nua, nua_hmagic_t *hmagic,
 /** Destroy a handle */
 SOFIAPUBFUN void nua_handle_destroy(nua_handle_t *h);
 
+/** Does not destroy the handle directly but forwards the nua_r_destroy_user event to the application so it could call nua_handle_destroy() from there. */
+SOFIAPUBFUN void nua_handle_destroy_user(nua_handle_t *h);
+
 /** Make a new reference to handle */
 SOFIAPUBFUN nua_handle_t *nua_handle_ref(nua_handle_t *);