[mid-]registrar: Refactor the "pn_inv_timeout" modparam

Refactor it into "pn_refresh_timeout", since now it's also used for
timing out EBR subscriptions for BYE, Re-INVITE, etc.

lib/reg/doc/pn_modparams.xml

@@ -172,20 +172,32 @@ modparam("&reg_module;", "pn_skip_pn_interval", 10)
 	</section>
 
 
-	<section id="param_pn_inv_timeout" xreflabel="pn_inv_timeout">
-		<title><varname>pn_inv_timeout</varname> (integer)</title>
-		<para>
-			This timeout starts counting following a &reg_lookup_f; which
-			triggers at least one Push Notification.  The value
-			represents the maximum allowed time for the Push Notifications and
-			their corresponding re-registrations from the awoken SIP UA to take
-			place.
-		</para>
-		<para>
-			Once this timeout is exceeded for the pending INVITE, any
-			further re-registrations corresponding to the pending Push
-			Notifications will no longer cause the INVITE to automatically
-			fork out to the registering devices.
+	<section id="param_pn_refresh_timeout" xreflabel="pn_refresh_timeout">
+		<title><varname>pn_refresh_timeout</varname> (integer)</title>
+		<para>
+			This timeout starts counting following a &reg_lookup_f; or a
+			<xref linkend="afunc_pn_process_purr()"/> which
+			triggers a Push Notification.  The value represents the maximum
+			allowed sum of the duration required for the Push Notification to
+			be sent and the duration required for the corresponding
+			re-registration from the device to arrive.
+		</para>
+		<para>
+			Once this timeout is exceeded for an initial or a mid-dialog
+			request, any further re-registrations which match the pending Push
+			Notification will no longer cause the desired effects. For example:
+			<itemizedlist>
+			<listitem><para>
+				pending initial INVITE transactions will complete and will no
+				longer auto-fork an additional branch for each REGISTER
+				sent by the callee side
+			</para></listitem>
+			<listitem><para>
+				pending BYE messages will time out and OpenSIPS will attempt to
+				route them despite having not received a confirmation that the
+				target device is actually reachable
+			</para></listitem>
+			</itemizedlist>
 		</para>
 		<para>
 			<emphasis>
@@ -194,10 +206,10 @@ modparam("&reg_module;", "pn_skip_pn_interval", 10)
 		</para>
 
 		<example>
-		<title>Setting the <varname>pn_inv_timeout</varname> parameter</title>
+		<title>Setting the <varname>pn_refresh_timeout</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("&reg_module;", "pn_inv_timeout", 5)
+modparam("&reg_module;", "pn_refresh_timeout", 10)
 ...
 </programlisting>
 		</example>

lib/reg/pn.c

@@ -37,7 +37,7 @@ int pn_enable;
 int pn_pnsreg_interval = 130;  /* sec */
 int pn_trigger_interval = 120; /* sec */
 int pn_skip_pn_interval = 0; /* sec */
-int pn_inv_timeout = 6; /* sec */
+int pn_refresh_timeout = 6; /* sec */
 int pn_enable_purr;
 char *_pn_ct_params = "pn-provider, pn-prid, pn-param";
 char *_pn_providers;
@@ -650,7 +650,7 @@ int pn_trigger_pn(struct sip_msg *req, const ucontact_t *ct,
 	}
 
 	if (ebr.notify_on_event(req, ev_ct_update, pn_ebr_filters,
-	        pn_trim_pn_params, pn_inject_branch, pn_inv_timeout) != 0) {
+	        pn_trim_pn_params, pn_inject_branch, pn_refresh_timeout) != 0) {
 		LM_ERR("failed to EBR-subscribe to "UL_EV_CT_UPDATE", Contact: %.*s\n",
 		       ct->c.len, ct->c.s);
 		return -1;
@@ -824,7 +824,7 @@ int pn_async_process_purr(struct sip_msg *req, async_ctx *ctx, udomain_t *d)
 
 	/* subscribe for re-register events from this contact */
 	if (ebr.async_wait_for_event(req, ctx, ev_ct_update, pn_ebr_filters,
-	          pn_trim_pn_params, pn_inv_timeout) != 0) {
+	          pn_trim_pn_params, pn_refresh_timeout) != 0) {
 		LM_ERR("failed to EBR-subscribe to "UL_EV_CT_UPDATE", ct: '%.*s'\n",
 		       c->c.len, c->c.s);
 		goto err_unlock;

lib/reg/pn.h

@@ -76,7 +76,7 @@ extern int pn_enable;
 extern int pn_pnsreg_interval;
 extern int pn_trigger_interval;
 extern int pn_skip_pn_interval;
-extern int pn_inv_timeout;
+extern int pn_refresh_timeout;
 extern int pn_enable_purr;
 extern char *_pn_ct_params;
 extern char *_pn_providers;
@@ -93,7 +93,7 @@ extern char *_pn_providers;
 	{"pn_pnsreg_interval",  INT_PARAM, &pn_pnsreg_interval}, \
 	{"pn_trigger_interval", INT_PARAM, &pn_trigger_interval}, \
 	{"pn_skip_pn_interval", INT_PARAM, &pn_skip_pn_interval}, \
-	{"pn_inv_timeout",      INT_PARAM, &pn_inv_timeout}, \
+	{"pn_refresh_timeout",  INT_PARAM, &pn_refresh_timeout}, \
 	{"pn_enable_purr",      INT_PARAM, &pn_enable_purr}
 
 

modules/mid_registrar/doc/mid_registrar.xml

@@ -3,7 +3,7 @@
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!ENTITY reg_module "<acronym>mid_registrar</acronym>">
-<!ENTITY reg_lookup_f "<emphasis><acronym>mid_reg_lookup()</acronym></emphasis>">
+<!ENTITY reg_lookup_f "<emphasis><acronym>mid_registrar_lookup()</acronym></emphasis>">
 
 <!ENTITY admin SYSTEM "mid_registrar_admin.xml">
 <!ENTITY contrib SYSTEM "contributors.xml">

modules/registrar/test/opensips.cfg

@@ -33,7 +33,7 @@ modparam("registrar", "pn_providers", "fcm, apns")
 modparam("registrar", "pn_ct_match_params", "pn-provider, pn-prid, pn-param")
 modparam("registrar", "pn_trigger_interval", 50)
 modparam("registrar", "pn_skip_pn_interval", 0)
-modparam("registrar", "pn_inv_timeout", 1)
+modparam("registrar", "pn_refresh_timeout", 2)
 
 loadmodule "usrloc.so"
 modparam("usrloc", "contact_refresh_timer", true)