Improve doc & code quality; Fix typos & inaccuracies

doc/build-contrib.sh

@@ -106,6 +106,7 @@ author_aliases=(
   ["root <root@opensips.org>"]="Bogdan-Andrei Iancu <bogdan@opensips.org>"
   ["rvlad-patrascu <vladp@opensips.org>"]="Vlad Patrascu <vladp@opensips.org>"
   ["rvlad-patrascu <rvlad.patrascu@gmail.com>"]="Vlad Patrascu <vladp@opensips.org>"
+  ["Vlad Pătrașcu <vladp@opensips.org>"]="Vlad Patrascu <vladp@opensips.org>"
   ["tallicamike <mtiganus@gmail.com>"]="Mihai Tiganus <mtiganus@gmail.com>"
 )
 

lib/reg/doc/pn_async_func.xml

@@ -12,12 +12,13 @@
 		usrloc contact is located, trigger an <ulink url='usrloc#event_E_UL_CONTACT_REFRESH'>E_UL_CONTACT_REFRESH</ulink>
 		event and place the request on async hold for at most
 		<xref linkend="param_pn_refresh_timeout"/> seconds, until a matching
-		Push Notification arrives.
+		REGISTER request arrives.
 		</para>
 
 		<para>
 		If processing ends before triggering the Push Notification, the request
-		will no longer block and the resume route will be immediately called.
+		will no longer be put on async hold, with the resume route being
+		immediately called.
 		</para>
 
 		<para>Meaning of the parameters is as follows:</para>

lib/reg/doc/pn_modparams.xml

@@ -59,9 +59,9 @@ modparam("&reg_module;", "pn_providers", "apns, fcm, webpush")
 			The minimally required list of RFC 8599 parameters (custom ones are
 			accepted as well) which must be present in a Contact URI and
 			identically match an existing binding in order for the binding
-			to be refreshed.  If at least one such parameter is missing from a
-			Contact header field URI, the module will fall back to performing
-			regular contact matching.
+			to be refreshed during a SIP re-REGISTER.  If at least one such
+			parameter is missing from a Contact header field URI, the module
+			will fall back to performing regular contact matching.
 		</para>
 		<para>
 			Note that if all above PN Contact URI parameters match an existing
@@ -235,11 +235,11 @@ modparam("&reg_module;", "pn_refresh_timeout", 10)
 			registration (PURR - Proxy Unique Registration Reference).
 		</para>
 		<para>
-			For each initial request for dialog, the UA may include the PURR
-			received from the &reg_module; in its Contact header (using the
-			<emphasis>";pn-purr"</emphasis> URI parameter) if it expects to be
-			first awoken by a Push Notification before being able to receive
-			mid-dialog request sent by the callee side.
+			During dialog setup, each UA may include, in its Contact header,
+			the PURR value returned by OpenSIPS during registration.  By
+			including the PURR (e.g. ";pn-purr=XXX"), an agent indicates that
+			it expects to be first awoken by a PN before being able to receive
+			a mid-dialog request sent by the other party.
 		</para>
 		<para>
 			When enabling this parameter, make sure to also add logic for

lib/reg/doc/supported_rfc.xml

@@ -136,9 +136,10 @@
 				the contact -- they may be found in the Contact URI ('uri'
 				event parameter) and may be extracted using the {uri.param,name}
 				transformation. From here onwards, it is up to the script
-				developer to trigger the Push Notification, thus forcing a
-				re-registration from the device (e.g. possibly by sending an
-				HTTP POST with the rest_client module)
+				developer to trigger the Push Notification (e.g. possibly by
+				sending an HTTP POST with the
+				<ulink url='rest_client'>rest_client</ulink> module), thus forcing
+				a re-registration from the device.
 			</para>
 			</listitem>
 			<listitem>

modules/auth/doc/auth_admin.xml

@@ -276,7 +276,7 @@ modparam("auth", "disable_nonce_check", 1)
 	<title>Exported Functions</title>
 	<section id="func_www_challenge" xreflabel="www_challenge()">
 		<title>
-			<function moreinfo="none">www_challenge(realm, qop)</function>
+			<function moreinfo="none">www_challenge(realm[, qop])</function>
 		</title>
 		<para>
 		The function challenges a user agent. It will generate a 
@@ -338,7 +338,7 @@ if (!www_authorize("siphub.net", "subscriber")) {
 
 	<section id="func_proxy_challenge" xreflabel="proxy_challenge()">
 		<title>
-			<function moreinfo="none">proxy_challenge(realm, qop)</function>
+			<function moreinfo="none">proxy_challenge(realm[, qop])</function>
 		</title>
 		<para>
 		The function challenges a user agent. It will generate a 

modules/cfgutils/test/cfgutils.c

@@ -40,7 +40,7 @@ extern int check_time_rec(struct sip_msg *_, char *time_rec,
 int ctr(const char *_rec, time_t *ts)
 {
 	char *rec;
-	int rc, len;
+	int rc;
 	time_t _ts;
 
 	if (!ts) {
@@ -49,10 +49,7 @@ int ctr(const char *_rec, time_t *ts)
 	}
 
 	/* it seems _tmrec_check_str() writes to the input buffer, so dup it! */
-	len = strlen(_rec);
-	rec = shm_malloc(len + 1);
-	memcpy(rec, _rec, len);
-	rec[len] = '\0';
+	rec = shm_strdup(_rec);
 
 	rc = _tmrec_check_str(rec, *ts);
 	shm_free(rec);
@@ -64,14 +61,11 @@ int ctr(const char *_rec, time_t *ts)
 int cmtr(const char *_rec, unsigned int ts)
 {
 	char *rec;
-	int rc1, rc2, len;
+	int rc1, rc2;
 	tmrec *tr;
 
 	/* it seems _tmrec_check_str() writes to the input buffer, so dup it! */
-	len = strlen(_rec);
-	rec = shm_malloc(len + 1);
-	memcpy(rec, _rec, len);
-	rec[len] = '\0';
+	rec = shm_strdup(_rec);
 
 	/* rc1: quick string parsing & evaluation */
 	rc1 = check_time_rec(NULL, rec, &ts);
@@ -472,19 +466,19 @@ void test_check_single_tmrec(void)
 	rc1 = ctr(US"|20200101T000000|20200101T120000||DAILY", NULL);
 	rc2 = ctr(US"|20200101T120000|20200102T000000||DAILY", NULL);
 	ok(rc1 != rc2);
-	rc2 = ctr(US"|20200101T120000|20200101T235959||DAILY", NULL);
+	rc2 = ctr(US"|20200101T120000|20200101T235960||DAILY", NULL);
 	ok(rc1 != rc2);
 
 	rc1 = ctr(NZ"|20200101T000000|20200101T120000||DAILY", NULL);
 	rc2 = ctr(NZ"|20200101T120000|20200102T000000||DAILY", NULL);
 	ok(rc1 != rc2);
-	rc2 = ctr(NZ"|20200101T120000|20200101T235959||DAILY", NULL);
+	rc2 = ctr(NZ"|20200101T120000|20200101T235960||DAILY", NULL);
 	ok(rc1 != rc2);
 
 	rc1 = ctr(UTC"|20200101T000000|20200101T120000||DAILY", NULL);
 	rc2 = ctr(UTC"|20200101T120000|20200102T000000||DAILY", NULL);
 	ok(rc1 != rc2);
-	rc2 = ctr(UTC"|20200101T120000|20200101T235959||DAILY", NULL);
+	rc2 = ctr(UTC"|20200101T120000|20200101T235960||DAILY", NULL);
 	ok(rc1 != rc2);
 
 	                      /* timezone checks (fixed time) */

modules/fraud_detection/doc/fraud_detection_admin.xml

@@ -11,7 +11,7 @@
 		Alerts are provided through return codes and events.
 	</para>
 		<section>
-		<title>Monitorized Stats</title>
+		<title>Monitored Stats</title>
 		<para>
 			Basically, this module watches the following parameters:
 			<itemizedlist>
@@ -540,11 +540,16 @@ modparam("fraud_detection", "seqcalls_thresh_crit_col", "seqcalls_crit_thresh")
 		<para>
 			This method should be called each time a given <emphasis>user</emphasis>
 			calls a given <emphasis>number</emphasis>. It will try to match a fraud rule
-			within de given fraud profile and update the stats (see above). Furthermore,
+			within the given fraud profile and update the stats (see above). Furthermore,
 			the stats will be checked against the rule's thresholds. If any of the stats
-			is above it's threshold value the appropriate event will also be raised
+			is above its threshold value, the appropriate event will also be raised
 			(see further details below).
 		</para>
+		<para>
+			Designed to only work with initial INVITE messages!  If a dialog is
+			not already present, one will be created (equivalent of
+			create_dialog()).
+		</para>
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
 		<listitem>

modules/fraud_detection/fraud_detection.c

@@ -406,7 +406,7 @@ static int check_fraud(struct sip_msg *msg, str *user, str *number, int *pid)
 
 	lock_release(&se->lock);
 
-	/* Set dialog callback to check call duration */
+	/* Set dialog callback to check call duration and decrement CC */
 	struct dlg_cell *dlgc = dlgb.get_dlg();
 	if (dlgc == NULL) {
 		if (dlgb.create_dlg(msg, 0) < 0) {

modules/freeswitch_scripting/doc/freeswitch_scripting_admin.xml

@@ -14,7 +14,7 @@
 		It allows the OpenSIPS script writer to subscribe
 		to generic FreeSWITCH ESL events as well as to run arbitrary
 		FreeSWITCH ESL commands and interpret their results.
-		It makes use of the <emphasis>freeswitch</emphasis>
+		It makes use of the <ulink url='freeswitch'>freeswitch</ulink>
 		module for the management of ESL connections and event subscriptions.
 	</para>
 	<para>

modules/gflags/doc/gflags_admin.xml

@@ -74,8 +74,7 @@ modparam("gflags", "initial", 15)
 		The <quote>flag</quote> (int) parameter can have a value in the range of 0..31.
 		</para>
 		<para>
-		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
+		This function may be used from any route.
 		</para>
 		<example>
 		<title><function moreinfo="none">set_gflag()</function> usage</title>
@@ -96,8 +95,7 @@ set_gflag(4);
 		The <quote>flag</quote> (int) parameter can have a value in the range of 0..31.
 		</para>
 		<para>
-		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
+		This function may be used from any route.
 		</para>
 		<example>
 		<title><function moreinfo="none">reset_gflag()</function> usage</title>
@@ -119,8 +117,7 @@ reset_gflag(4);
 		The <quote>flag</quote> (int) parameter can have a value in the range of 0..31.
 		</para>
 		<para>
-		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
+		This function may be used from any route.
 		</para>
 		<example>
 		<title><function moreinfo="none">is_gflag()</function> usage</title>

modules/mid_registrar/doc/mid_registrar_admin.xml

@@ -205,6 +205,12 @@
 				<emphasis>tm</emphasis>
 			</para>
 			</listitem>
+			<listitem>
+			<para>
+				<emphasis>event_routing</emphasis>,
+				if <xref linkend="param_pn_enable"/> is set to <emphasis>true</emphasis>.
+			</para>
+			</listitem>
 			</itemizedlist>
 		</para>
 	</section>

modules/qrouting/doc/qrouting_admin.xml

@@ -31,8 +31,9 @@
 <section id="monitored_statistics" xreflabel="Monitored Statistics">
 	<title>Monitored Statistics</title>
 	<para>
-	The module keeps track of the following statistics, <emphasis role='bold'>
-	for each drouting gateway</emphasis>:
+	The module keeps track of a series of statistics, for each drouting
+	<emphasis role='bold'>(prefix, destination)</emphasis> pair, where a
+	"destination" may be either a gateway or a carrier.  The statistics are:
 	<itemizedlist>
 		<listitem>
 			<para>ASR (Answer Seizure Ratio) - the percentage of telephone
@@ -404,7 +405,7 @@ modparam("qrouting", "min_samples_acd", 30)
 		<para>
 		The minimally accepted quality of a (prefix, destination) combination,
 		given as a quoted floating point number in the [0, 1] interval.
-		Whenever a (prefix + destination combination) receives a score below
+		Whenever a (prefix, destination) combination receives a score below
 		this threshold, the <xref linkend="event_E_QROUTING_BAD_DST"/> event
 		will be triggered.
 		</para>
@@ -710,8 +711,9 @@ opensips-cli -x mi qr_enable_dst pstn 81 MY-GW-3
 		<function moreinfo="none">E_QROUTING_BAD_DST</function>
 		</title>
 		<para>
-		This event may be raised during routing, asynchronously, whenever a
-		gateway's score falls below <xref linkend="param_event_bad_dst_threshold"/>.
+		This event may be raised during routing, asynchronously, whenever the
+		score of a (prefix, destination) pair falls below
+		<xref linkend="param_event_bad_dst_threshold"/>.
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>

modules/registrar/doc/registrar_admin.xml

@@ -33,6 +33,12 @@
 				<emphasis>signaling - Signaling module</emphasis>.
 			</para>
 			</listitem>
+			<listitem>
+			<para>
+				<emphasis>event_routing</emphasis>,
+				if <xref linkend="param_pn_enable"/> is set to <emphasis>true</emphasis>.
+			</para>
+			</listitem>
 			</itemizedlist>
 		</para>
 	</section>

modules/rest_client/doc/rest_client_admin.xml

@@ -299,15 +299,15 @@ modparam("rest_client", "enable_expect_100", true)
 				<emphasis>url</emphasis> (string)
 			</para></listitem>
 			<listitem><para>
-				<emphasis>body_pv</emphasis> (var) - variable that will hold the
+				<emphasis>body_pv</emphasis> (var) - output variable which will hold the
 				body of the HTTP response.
 			</para></listitem>
 			<listitem><para>
-				<emphasis>ctype_pv</emphasis> (var, optional) - variable thah will
+				<emphasis>ctype_pv</emphasis> (var, optional) - output variable which will
 				contain the value of the "Content-Type:" header of the response.
 			</para></listitem>
 			<listitem><para>
-				<emphasis>retcode_pv</emphasis> (var, optional) - variable that will
+				<emphasis>retcode_pv</emphasis> (var, optional) - output variable which will
 				retain the status code of the HTTP response.
 				A <emphasis role='bold'>0</emphasis> status code value means no HTTP
 				reply arrived at all.
@@ -372,16 +372,17 @@ if ($var(rcode) != 200) {
 				<emphasis>"application/x-www-form-urlencoded"</emphasis>
 			</para></listitem>
 			<listitem><para>
-				<emphasis>recv_body_pv</emphasis> (var) - the variable will hold
-				the body of the HTTP response.
+				<emphasis>recv_body_pv</emphasis> (var) - output variable which
+				will hold the body of the HTTP response.
 			</para></listitem>
 			<listitem><para>
-				<emphasis>recv_ctype_pv</emphasis> (var, optional) - will contain
-				the value of the "Content-Type" header of the response
+				<emphasis>recv_ctype_pv</emphasis> (var, optional) - output
+				variable which will contain the value of the "Content-Type"
+				header of the response
 			</para></listitem>
 			<listitem><para>
-				<emphasis>retcode_pv</emphasis> (var, optional) - variable that will
-				retain the status code of the HTTP response.
+				<emphasis>retcode_pv</emphasis> (var, optional) - output variable
+				which will retain the status code of the HTTP response.
 				A <emphasis role='bold'>0</emphasis> status code value means no HTTP
 				reply arrived at all.
 			</para></listitem>
@@ -444,16 +445,16 @@ if ($var(rcode) != 200) {
 				<emphasis>"application/x-www-form-urlencoded"</emphasis>
 			</para></listitem>
 			<listitem><para>
-				<emphasis>recv_body_pv</emphasis> (var) - the variable will hold
-				the body of the HTTP response.
+				<emphasis>recv_body_pv</emphasis> (var) - output variable which
+				will hold the body of the HTTP response.
 			</para></listitem>
 			<listitem><para>
-				<emphasis>recv_ctype_pv</emphasis> (var, optional) - will contain
-				the value of the "Content-Type" header of the response
+				<emphasis>recv_ctype_pv</emphasis> (var, optional) - output variable
+				which will contain the value of the "Content-Type" header of the response
 			</para></listitem>
 			<listitem><para>
-				<emphasis>retcode_pv</emphasis> (var, optional) - variable that will
-				retain the status code of the HTTP response.
+				<emphasis>retcode_pv</emphasis> (var, optional) - output variable
+				which will retain the status code of the HTTP response.
 				A <emphasis role='bold'>0</emphasis> status code value means no HTTP
 				reply arrived at all.
 			</para></listitem>
@@ -525,8 +526,9 @@ $var(rc) = rest_get("http://getcredit.org/?account=$fU", $var(credit));
 		<function moreinfo="none">rest_init_client_tls(tls_client_domain)</function>
 		</title>
 		<para>
-		Force a specific TLS domain to be eventually used during the next request.
-		Refer to the tls_mgm module for additional info regarding TLS client domains.
+		Force a specific TLS domain to be used at most once, during the next
+		GET/POST/PUT request.  Refer to the tls_mgm module for additional info
+		regarding TLS client domains.
 		</para>
 		<para>
 		If using this function, you must also ensure that tls_mgm is loaded
@@ -685,7 +687,13 @@ route [resume] {
     <section id="exported_transformations">
         <title>Exported script transformations</title>
         <para>
-            The module also provides a way for encoding and decoding parameters contained in a arbitrary script variable, in accordance with RFC3986. This is done by applying a transformation to a script variable containing the data to be encoded. The value of the original variable is not altered and a corresponding string value is returned. The transformation is performed through libcurl API method curl_easy_escape (or curl_escape for libcurl &lt; 7.15.4).
+			The module also provides a way for encoding and decoding parameters
+			contained in an arbitrary script variable, in accordance with
+			RFC3986. This is done by applying a transformation to a script
+			variable containing the data to be encoded. The value of the
+			original variable is not altered and a corresponding string value
+			is returned. The transformation is performed through libcurl API
+			method curl_easy_escape (or curl_escape for libcurl &lt; 7.15.4).
         </para>
 
         <section id="tran_rest.escape" xreflabel="rest.escape">

modules/rr/record.c

@@ -279,7 +279,7 @@ int record_route(struct sip_msg* _m, str *params)
 		if (ap->type==HDR_RECORDROUTE_T && ap->op==LUMP_NOP
 		&& ap->before && ap->before->op==LUMP_ADD_OPT
 		&& ap->before->u.cond==COND_FALSE) {
-			/* found our phony anchor lump -> hide it for future searches */
+			/* found our phony anchor lump -> hide it from future searches */
 			ap->type = HDR_ERROR_T;
 
 			/* jump over the anchor and conditional lumps */
@@ -427,7 +427,7 @@ int record_route_preset(struct sip_msg* _m, str* _data)
 		if (ap->type==HDR_RECORDROUTE_T && ap->op==LUMP_NOP
 		&& ap->before && ap->before->op==LUMP_ADD_OPT
 		&& ap->before->u.cond==COND_FALSE) {
-			/* found our phony anchor lump -> hide it for future searches */
+			/* found our phony anchor lump -> hide it from future searches */
 			ap->type = HDR_ERROR_T;
 
 			/* jump over the anchor and conditional lumps */