[Asterisk-code-review] func callerid: Document that CALLERID(pres) is available. (asterisk[11])

[Walter Doekes]

Walter Doekes has uploaded a new change for review.

  https://gerrit.asterisk.org/1584

Change subject: func_callerid: Document that CALLERID(pres) is available.
......................................................................

func_callerid: Document that CALLERID(pres) is available.

CALLERPRES() says that it's deprecated in favor of CALLERID(num-pres)
and CALLERID(name-pres).  But for channel driver that don't make a
distinction between the two (e.g. SIP), it makes more sense to get/set
both at once.  This change reveals the availability of CALLERID(pres)
and CONNECTEDLINE(pres).

ASTERISK-25373 #close

Change-Id: I5614ae4ab7d3bbe9c791c1adf147e10de8698d7a
---
M CHANGES
M funcs/func_callerid.c
2 files changed, 32 insertions(+), 10 deletions(-)


  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/84/1584/1

diff --git a/CHANGES b/CHANGES
index 449c2e7..0ea9756 100644
--- a/CHANGES
+++ b/CHANGES
@@ -9,7 +9,20 @@
 ==============================================================================
 
 ------------------------------------------------------------------------------
---- Functionality changes since Asterisk 11.15 --------------------------------
+--- Functionality changes since Asterisk 11.21 -------------------------------
+------------------------------------------------------------------------------
+
+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).
+
+------------------------------------------------------------------------------
+--- Functionality changes since Asterisk 11.15 -------------------------------
 ------------------------------------------------------------------------------
 
 res_fax
diff --git a/funcs/func_callerid.c b/funcs/func_callerid.c
index 1af4218..c628102 100644
--- a/funcs/func_callerid.c
+++ b/funcs/func_callerid.c
@@ -40,10 +40,10 @@
 #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.
  *
  * Do not document the CALLERID(ton) datatype.
  * It is an alias for num-plan.
@@ -55,10 +55,10 @@
  * 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.
+ * The CONNECTEDLINE(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.
  *
  * Do not document the CONNECTEDLINE(ton) datatype.
  * It is an alias for num-plan.
@@ -98,6 +98,7 @@
 					<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 +145,9 @@
 		<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 +172,8 @@
 		<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 +223,7 @@
 					<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 +252,9 @@
 		</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>

-- 
To view, visit https://gerrit.asterisk.org/1584
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I5614ae4ab7d3bbe9c791c1adf147e10de8698d7a
Gerrit-PatchSet: 1
Gerrit-Project: asterisk
Gerrit-Branch: 11
Gerrit-Owner: Walter Doekes <walter+asterisk at wjd.nu>