Merged revisions 284698 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/1.8

........
  r284698 | rmudgett | 2010-09-02 11:34:32 -0500 (Thu, 02 Sep 2010) | 5 lines

  Added documentation for CONNECTEDLINE and REDIRECTING functions.

  (closes issue #17808)
  Reported by: jtodd

  Review: https://reviewboard.asterisk.org/r/875/
........


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@284699 65c4cc65-6c06-0410-ace0-fbb531ad65f3

3 files changed, 346 insertions, 5 deletions

diff --git a/doc/tex/asterisk.tex b/doc/tex/asterisk.tex
index 4cf45df15..38d58bdef 100644
--- a/doc/tex/asterisk.tex
+++ b/doc/tex/asterisk.tex
@@ -151,6 +151,9 @@ reference purposes.
 \chapter{Secure Calls}
   \input{secure-calls.tex}
 
+\chapter{Manipulating Party ID Information}
+  \input{partymanip.tex}
+
 \chapter{Call Completion Supplementary Services}
   \input{ccss.tex}
 
diff --git a/doc/tex/channelvariables.tex b/doc/tex/channelvariables.tex
index 07f887269..a493e05fb 100644
--- a/doc/tex/channelvariables.tex
+++ b/doc/tex/channelvariables.tex
@@ -1044,10 +1044,23 @@ ${OSPINAUDIOQOS}        The inbound call leg audio QoS string.
 ${OSPOUTAUDIOQOS}       The outbound call leg audio QoS string.
 \end{verbatim}
 
-\subsection{Connected line digit manipulation}
+\subsection{Digit manipulation}
 \begin{verbatim}
-${CONNECTED_LINE_SEND_CALLEE_MACRO}        Macro to call before sending a connected line update to the callee
-${CONNECTED_LINE_SEND_CALLEE_MACRO_ARGS}   Arguments to pass to ${CONNECTED_LINE_SEND_CALLEE_MACRO}
-${CONNECTED_LINE_SEND_CALLER_MACRO}        Macro to call before sending a connected line update to the caller
-${CONNECTED_LINE_SEND_CALLER_MACRO_ARGS}   Arguments to pass to ${CONNECTED_LINE_SEND_CALLER_MACRO}
+${REDIRECTING_SEND_CALLEE_MACRO}
+  Macro to call before sending a redirecting update to the callee
+${REDIRECTING_SEND_CALLEE_MACRO_ARGS}
+  Arguments to pass to ${REDIRECTING_SEND_CALLEE_MACRO}
+${REDIRECTING_SEND_CALLER_MACRO}
+  Macro to call before sending a redirecting update to the caller
+${REDIRECTING_SEND_CALLER_MACRO_ARGS}
+  Arguments to pass to ${REDIRECTING_SEND_CALLER_MACRO}
+
+${CONNECTED_LINE_SEND_CALLEE_MACRO}
+  Macro to call before sending a connected line update to the callee
+${CONNECTED_LINE_SEND_CALLEE_MACRO_ARGS}
+  Arguments to pass to ${CONNECTED_LINE_SEND_CALLEE_MACRO}
+${CONNECTED_LINE_SEND_CALLER_MACRO}
+  Macro to call before sending a connected line update to the caller
+${CONNECTED_LINE_SEND_CALLER_MACRO_ARGS}
+  Arguments to pass to ${CONNECTED_LINE_SEND_CALLER_MACRO}
 \end{verbatim}
diff --git a/doc/tex/partymanip.tex b/doc/tex/partymanip.tex
new file mode 100644
index 000000000..2ca05569f
--- /dev/null
+++ b/doc/tex/partymanip.tex
@@ -0,0 +1,325 @@
+\section{Introduction}
+
+This chapter aims to explain how to use some of the features available to
+manipulate party ID information.  It will not delve into specific channel
+configuration options described in the respective sample configuration
+files.  The party ID information can consist of Caller ID, Connected Line
+ID, redirecting to party ID information, and redirecting from party ID
+information.  Meticulous control is needed particularly when
+interoperating between different channel technologies.
+
+\begin{itemize}
+
+\item Caller ID: The Caller ID information describes who is originating a
+call.
+
+\item Connected Line ID: The Connected Line ID information describes who
+is connected to the other end of a call while a call is established.
+Unlike Caller ID, the connected line information can change over the life
+of a call when call transfers are performed.  The connected line
+information can also change in either direction because either end could
+transfer the call.  For ISDN it is known as Connected Line Identification
+Presentation (COLP), Connected Line Identification Restriction (COLR), and
+Explicit Call Transfer (ECT).  For SIP it is known either as
+P-Asserted-Identity or Remote-Party-Id.
+
+\item Redirecting information: When a call is forwarded, the call
+originator is informed that the call is redirecting-to a new destination.
+The new destination is also informed that the incoming call is
+redirecting-from the forwarding party.  A call can be forwarded repeatedly
+until a new destination answers it or a forwarding limit is reached.
+
+\end{itemize}
+
+\section{Tools available}
+
+Asterisk contains several tools for manipulating the party ID information
+for a call.  Additional information can be found by using the 'core show
+function' or 'core show application' console commands at the Asterisk CLI.
+The following list identifies some of the more common tools for
+manipulating the party ID information:
+
+\begin{itemize}
+\item CALLERID(datatype[,caller-id])
+
+\item CONNECTEDLINE(datatype[,i])
+
+\item REDIRECTING(datatype[,i])
+
+\item Dial() and Queue() dialplan application 'I' option
+
+\item Interception macros
+
+\item Channel driver specific configuration options.
+\end{itemize}
+
+\subsection{CALLERID dialplan function}
+
+The CALLERID function has been around for quite a while and its use is
+straightforward.  It is used to examine and alter the caller information
+that came into the dialplan with the call.  Then the call with it's caller
+information passes on to the destination using the Dial() or Queue()
+application.
+
+The CALLERID information is passed during the initial call setup.
+However, depending on the channel technology, the caller name may be
+delayed.  Q.SIG is an example where the caller name may be delayed so your
+dialplan may need to wait for it.
+
+\subsection{CONNECTEDLINE dialplan function}
+
+The CONNECTEDLINE function does the opposite of the CALLERID function.
+CONNECTEDLINE can be used to setup connected line information to be sent when the
+call is answered.  You can use it to send new connected line information
+to the remote party on the channel when a call is transferred.  The
+CONNECTEDLINE information is passed when the call is answered and when the
+call is transferred.
+
+Since the connected line information can be sent while a call is
+connected, you may need to prevent the channel driver from acting on a
+partial update.  The 'i' option is used to inhibit the channel driver from
+sending the changed information immediately.
+
+\subsection{REDIRECTING dialplan function}
+
+The REDIRECTING function allows you to report information about
+forwarded/deflected calls to the caller and to the new destination.  The
+use of the REDIRECTING function is the most complicated of the party
+information functions.
+
+The REDIRECTING information is passed during the initial call setup and
+while the call is being routed through the network.  Since the redirecting
+information is sent before a call is answered, you need to prevent the
+channel driver from acting on a partial update.  The 'i' option is used to
+inhibit the channel driver from sending the changed information
+immediately.
+
+The incoming call may have already been redirected.  An incoming call has
+already been redirected if the REDIRECTING(count) is not zero.  (Alternate
+indications are if the REDIRECTING(from-num-valid) is non-zero or if the
+REDIRECTING(from-num) is not empty.)
+
+There are several things to do when a call is forwarded by the dialplan:
+
+\begin{itemize}
+
+\item Setup the REDIRECTING(to-xxx) values to be sent to the caller.
+
+\item Setup the REDIRECTING(from-xxx) values to be sent to the new
+destination.
+
+\item Increment the REDIRECTING(count).
+
+\item Set the REDIRECTING(reason).
+
+\item Dial() the new destination.
+
+\end{itemize}
+
+\subsection{Special REDIRECTING considerations for ISDN}
+
+Special considerations for Q.SIG and ISDN point-to-point links are needed
+to make the DivertingLegInformation1, DivertingLegInformation2, and
+DivertingLegInformation3 messages operate properly.
+
+You should manually send the COLR of the redirected-to party for an
+incoming redirected call if the incoming call could experience further
+redirects.  For chan_misdn, just set the REDIRECTING(to-num,i) =
+\$\{EXTEN\} and set the REDIRECTING(to-num-pres) to the COLR.  For
+chan_dahdi, just set the REDIRECTING(to-num,i) = CALLERID(dnid) and set
+the REDIRECTING(to-num-pres) to the COLR.  (Setting the
+REDIRECTING(to-num,i) value may not be necessary since the channel driver
+has already attempted to preset that value for automatic generation of the
+needed DivertingLegInformation3 message.)
+
+For redirected calls out a trunk line, you need to use the 'i' option on
+all of the REDIRECTING statements before dialing the redirected-to party.
+The call will update the redirecting-to presentation (COLR) when it
+becomes available.
+
+\subsection{Dial() and Queue() dialplan application 'I' option}
+
+In the dialplan applications Dial() and Queue(), the 'I' option is a brute
+force option to block connected line and redirecting information updates
+while the application is running.  Blocking the updates prevents the
+update from overwriting any CONNECTEDLINE or REDIRECTING values you may
+have setup before running the application.
+
+The option blocks all redirecting updates since they should only happen
+before a call is answered.  The option only blocks the connected line
+update from the initial answer.  Connected line updates resulting from
+call transfers happen after the application has completed.  Better control
+of connected line and redirecting information is obtained using the
+interception macros.
+
+\subsection{Interception macros}
+
+The interception macros give the administrator an opportunity to alter
+connected line and redirecting information before the channel driver is
+given the information.  If the macro does not change a value then that is
+what is going to be passed to the channel driver.
+
+The tag string available in CALLERID, CONNECTEDLINE, and REDIRECTING is
+useful for the interception macros to provide some information about where
+the information originally came from.
+
+\begin{verbatim}
+${REDIRECTING_SEND_CALLEE_MACRO}
+  Macro to call before sending a redirecting update to the callee.
+  This macro may never be needed since the redirecting updates
+  should only go from the callee to the caller direction.  It is
+  available for completeness.
+${REDIRECTING_SEND_CALLEE_MACRO_ARGS}
+  Arguments to pass to ${REDIRECTING_SEND_CALLEE_MACRO}.
+
+${REDIRECTING_SEND_CALLER_MACRO}
+  Macro to call before sending a redirecting update to the caller.
+${REDIRECTING_SEND_CALLER_MACRO_ARGS}
+  Arguments to pass to ${REDIRECTING_SEND_CALLER_MACRO}.
+
+${CONNECTED_LINE_SEND_CALLEE_MACRO}
+  Macro to call before sending a connected line update to the callee.
+${CONNECTED_LINE_SEND_CALLEE_MACRO_ARGS}
+  Arguments to pass to ${CONNECTED_LINE_SEND_CALLEE_MACRO}.
+
+${CONNECTED_LINE_SEND_CALLER_MACRO}
+  Macro to call before sending a connected line update to the caller.
+${CONNECTED_LINE_SEND_CALLER_MACRO_ARGS}
+  Arguments to pass to ${CONNECTED_LINE_SEND_CALLER_MACRO}.
+\end{verbatim}
+
+\section{Manipulation examples}
+
+The following examples show several common scenarios in which you may need
+to manipulate party ID information from the dialplan.
+
+\subsection{Simple recording playback}
+
+\begin{verbatim}
+exten => 1000,1,NoOp
+; The CONNECTEDLINE information is sent when the call is answered.
+exten => 1000,n,Set(CONNECTEDLINE(name,i)="Company Name")
+exten => 1000,n,Set(CONNECTEDLINE(name-pres,i)=allowed)
+exten => 1000,n,Set(CONNECTEDLINE(num,i)=5551212)
+exten => 1000,n,Set(CONNECTEDLINE(num-pres)=allowed)
+exten => 1000,n,Answer
+exten => 1000,n,Playback(tt-weasels)
+exten => 1000,n,Hangup
+\end{verbatim}
+
+\subsection{Straightforward dial through}
+
+\begin{verbatim}
+exten => 1000,1,NoOp
+; The CONNECTEDLINE information is sent when the call is answered.
+exten => 1000,n,Set(CONNECTEDLINE(name,i)="Company Name")
+exten => 1000,n,Set(CONNECTEDLINE(name-pres,i)=allowed)
+exten => 1000,n,Set(CONNECTEDLINE(num,i)=5551212)
+exten => 1000,n,Set(CONNECTEDLINE(num-pres)=allowed)
+; The I option prevents overwriting the CONNECTEDLINE information
+; set above when the call is answered.
+exten => 1000,n,Dial(SIP/1000,20,I)
+exten => 1000,n,Hangup
+\end{verbatim}
+
+\subsection{Use of interception macro}
+
+\begin{verbatim}
+[macro-add_pfx]
+; ARG1 is the prefix to add.
+; ARG2 is the number of digits at the end to add the prefix to.
+; When the macro ends the CONNECTEDLINE data is passed to the
+; channel driver.
+exten => s,1,NoOp(Add prefix to connected line)
+exten => s,n,Set(NOPREFIX=${CONNECTEDLINE(number):-${ARG2}})
+exten => s,n,Set(CONNECTEDLINE(num,i)=${ARG1}${NOPREFIX})
+exten => s,n,MacroExit
+
+exten => 1000,1,NoOp
+exten => 1000,n,Set(__CONNECTED_LINE_CALLER_SEND_MACRO=add_pfx)
+exten => 1000,n,Set(__CONNECTED_LINE_CALLER_SEND_MACRO_ARGS=45,4)
+exten => 1000,n,Dial(SIP/1000,20)
+exten => 1000,n,Hangup
+\end{verbatim}
+
+\subsection{Simple redirection}
+\begin{verbatim}
+exten => 1000,1,NoOp
+; For Q.SIG or ISDN point-to-point we should determine the COLR for this
+; extension and send it if the call was redirected here.
+exten => 1000,n,GotoIf($[${REDIRECTING(count)}>0]?redirected:notredirected)
+exten => 1000,n(redirected),Set(REDIRECTING(to-num,i)=${CALLERID(dnid)})
+exten => 1000,n,Set(REDIRECTING(to-num-pres)=allowed)
+exten => 1000,n(notredirected),NoOp
+; Determine that the destination has forwarded the call.
+; ...
+exten => 1000,n,Set(REDIRECTING(from-num,i)=1000)
+exten => 1000,n,Set(REDIRECTING(from-num-pres,i)=allowed)
+exten => 1000,n,Set(REDIRECTING(to-num,i)=2000)
+; The DivertingLegInformation3 message is needed because at this point
+; we do not know the presentation (COLR) setting of the redirecting-to
+; party.
+exten => 1000,n,Set(REDIRECTING(count,i)=$[${REDIRECTING(count)} + 1])
+exten => 1000,n,Set(REDIRECTING(reason,i)=cfu)
+; The call will update the redirecting-to presentation (COLR) when it
+; becomes available with a redirecting update.
+exten => 1000,n,Dial(DAHDI/g1/2000,20)
+exten => 1000,n,Hangup
+\end{verbatim}
+
+\section{Ideas for usage}
+
+The following is a list of ideas in which the manipulation of party ID
+information would be beneficial.
+
+\begin{itemize}
+
+\item IVR that updates connected name on each selection made.
+
+\item Disguise the true number of an individual with a generic company
+number.
+
+\item Use interception macros to make outbound connected number E.164
+formatted.
+
+\item You can do a lot more in an interception macro than just manipulate
+party information...
+
+\end{itemize}
+
+\section{Troubleshooting tips}
+\begin{itemize}
+
+\item For CONNECTEDLINE and REDIRECTING, check the usage of the 'i'
+option.
+
+\item Check channel configuration settings.  The default settings may not
+be what you want or expect.
+
+\item Check packet captures.  Your equipment may not support what Asterisk
+sends.
+
+\end{itemize}
+
+\section{For further reading...}
+\begin{itemize}
+
+\item Relevant ETSI ISDN redirecting specification: EN 300 207-1
+
+\item Relevant ETSI ISDN COLP specification: EN 300 097-1
+
+\item Relevant ETSI ISDN ECT specification: EN 300 369-1
+
+\item Relevant Q.SIG ISDN redirecting specification: ECMA-174
+
+\item Relevant Q.SIG ISDN COLP specification: ECMA-148
+
+\item Relevant Q.SIG ISDN ECT specification: ECMA-178
+
+\item Relevant SIP RFC for P-Asserted-Id: RFC3325
+
+\item The expired draft (draft-ietf-sip-privacy-04.txt) defines
+Remote-Party-Id.  Since Remote-Party-Id has not made it into an RFC at
+this time, its use is non-standard by definition.
+
+\end{itemize}