Merge "func_callerid: Document that CALLERID(pres) is available."

CHANGES

@@ -221,6 +221,16 @@ res_pjsip
  * The ability to use "like" has been added to the pjsip list and show
    CLI commands.  For instance: CLI> pjsip list endpoints like abc
 
+func_callerid
+-------------------
+ * CALLERID(pres) is now documented as a valid alternative to setting both
+   CALLERID(name-pres) and CALLERID(num-pres) at once.  Some channel drivers,
+   like chan_sip, don't make a distinction between the two: they take the
+   least public value from name-pres and num-pres.  By using CALLERID(pres)
+   for reading and writing, you touch the same combined value in the dialplan.
+   The same applies to CONNECTEDLINE(pres), REDIRECTING(orig-pres),
+   REDIRECTING(to-pres) and REDIRECTING(from-pres).
+
 ------------------------------------------------------------------------------
 --- Functionality changes from Asterisk 13.5.0 to Asterisk 13.6.0 ------------
 ------------------------------------------------------------------------------

funcs/func_callerid.c

@@ -40,10 +40,11 @@ ASTERISK_REGISTER_FILE()
 #include "asterisk/callerid.h"
 
 /*
- * Do not document the CALLERID(pres) datatype.
- * The name and number now have their own presentation value.  The pres
- * option will simply live on as a historical relic with as best
- * as can be managed backward compatible meaning.
+ * The CALLERID(pres) datatype is shorthand for getting/setting the
+ * combined value of name-pres and num-pres.  Some channel drivers
+ * don't make a distinction, so it makes sense to only use one property
+ * to get/set it.  The same applies to CONNECTEDLINE(pres),
+ * REDIRECTING(orig-pres), REDIRECTING(from-pres) and REDIRECTING(to-pres).
  *
  * Do not document the CALLERID(ton) datatype.
  * It is an alias for num-plan.
@@ -55,11 +56,6 @@ ASTERISK_REGISTER_FILE()
  * It has turned out to not be needed.  The source value is really
  * only useful as a possible tracing aid.
  *
- * Do not document the CONNECTEDLINE(pres) datatype.
- * The name and number now have their own presentation value.  The pres
- * option will simply live on as a historical relic with as best
- * as can be managed backward compatible meaning.
- *
  * Do not document the CONNECTEDLINE(ton) datatype.
  * It is an alias for num-plan.
  *
@@ -69,12 +65,6 @@ ASTERISK_REGISTER_FILE()
  * they are active at the same time.  The plain pres option will simply
  * live on as a historical relic.
  *
- * Do not document the REDIRECTING(orig-pres), REDIRECTING(from-pres),
- * or REDIRECTING(to-pres) datatypes.
- * The name and number now have their own presentation value.  The orig-pres,
- * from-pres, and to-pres options will simply live on as a historical relic
- * with as best as can be managed backward compatible meaning.
- *
  * Do not document the REDIRECTING(orig-ton), REDIRECTING(from-ton),
  * or REDIRECTING(to-ton) datatypes.
  * They are aliases for orig-num-plan, from-num-plan, and to-num-plan
@@ -98,6 +88,7 @@ ASTERISK_REGISTER_FILE()
 					<enum name = "num-valid" />
 					<enum name = "num-plan" />
 					<enum name = "num-pres" />
+					<enum name = "pres" />
 					<enum name = "subaddr" />
 					<enum name = "subaddr-valid" />
 					<enum name = "subaddr-type" />
@@ -144,6 +135,9 @@ ASTERISK_REGISTER_FILE()
 		<description>
 			<para>Gets or sets Caller*ID data on the channel. Uses channel callerid by
 			default or optional callerid, if specified.</para>
+			<para>The <replaceable>pres</replaceable> field gets/sets a combined value
+			for <replaceable>name-pres</replaceable> and
+			<replaceable>num-pres</replaceable>.</para>
 			<para>The allowable values for the <replaceable>name-charset</replaceable>
 			field are the following:</para>
 			<enumlist>
@@ -168,7 +162,8 @@ ASTERISK_REGISTER_FILE()
 		<description>
 			<para>Gets or sets Caller*ID presentation on the channel.
 			This function is deprecated in favor of CALLERID(num-pres)
-			and CALLERID(name-pres).
+			and CALLERID(name-pres) or CALLERID(pres) to get/set both
+			at once.
 			The following values are valid:</para>
 			<enumlist>
 				<enum name="allowed_not_screened">
@@ -218,6 +213,7 @@ ASTERISK_REGISTER_FILE()
 					<enum name = "num-valid" />
 					<enum name = "num-plan" />
 					<enum name = "num-pres" />
+					<enum name = "pres" />
 					<enum name = "subaddr" />
 					<enum name = "subaddr-valid" />
 					<enum name = "subaddr-type" />
@@ -246,6 +242,9 @@ ASTERISK_REGISTER_FILE()
 		</syntax>
 		<description>
 			<para>Gets or sets Connected Line data on the channel.</para>
+			<para>The <replaceable>pres</replaceable> field gets/sets a combined value
+			for <replaceable>name-pres</replaceable> and
+			<replaceable>num-pres</replaceable>.</para>
 			<para>The allowable values for the <replaceable>name-charset</replaceable>
 			field are the following:</para>
 			<enumlist>
@@ -279,6 +278,7 @@ ASTERISK_REGISTER_FILE()
 					<enum name = "orig-num-valid" />
 					<enum name = "orig-num-plan" />
 					<enum name = "orig-num-pres" />
+					<enum name = "orig-pres" />
 					<enum name = "orig-subaddr" />
 					<enum name = "orig-subaddr-valid" />
 					<enum name = "orig-subaddr-type" />
@@ -294,6 +294,7 @@ ASTERISK_REGISTER_FILE()
 					<enum name = "from-num-valid" />
 					<enum name = "from-num-plan" />
 					<enum name = "from-num-pres" />
+					<enum name = "from-pres" />
 					<enum name = "from-subaddr" />
 					<enum name = "from-subaddr-valid" />
 					<enum name = "from-subaddr-type" />
@@ -308,6 +309,7 @@ ASTERISK_REGISTER_FILE()
 					<enum name = "to-num-valid" />
 					<enum name = "to-num-plan" />
 					<enum name = "to-num-pres" />
+					<enum name = "to-pres" />
 					<enum name = "to-subaddr" />
 					<enum name = "to-subaddr-valid" />
 					<enum name = "to-subaddr-type" />
@@ -366,6 +368,11 @@ ASTERISK_REGISTER_FILE()
 		</syntax>
 		<description>
 			<para>Gets or sets Redirecting data on the channel.</para>
+			<para>The <replaceable>orig-pres</replaceable>,
+			<replaceable>from-pres</replaceable> and <replaceable>to-pres</replaceable>
+			fields get/set a combined value for the corresponding
+			<replaceable>...-name-pres</replaceable> and <replaceable>...-num-pres</replaceable>
+			fields.</para>
 			<para>The allowable values for the <replaceable>reason</replaceable>
 			and <replaceable>orig-reason</replaceable> fields are the following:</para>
 			<enumlist>