[asterisk-commits] rmudgett: branch 1.8 r284698 - /branches/1.8/doc/tex/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Thu Sep 2 11:34:37 CDT 2010
Author: rmudgett
Date: Thu Sep 2 11:34:32 2010
New Revision: 284698
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=284698
Log:
Added documentation for CONNECTEDLINE and REDIRECTING functions.
(closes issue #17808)
Reported by: jtodd
Added:
branches/1.8/doc/tex/partymanip.tex (with props)
Modified:
branches/1.8/doc/tex/asterisk.tex
branches/1.8/doc/tex/channelvariables.tex
Modified: branches/1.8/doc/tex/asterisk.tex
URL: http://svnview.digium.com/svn/asterisk/branches/1.8/doc/tex/asterisk.tex?view=diff&rev=284698&r1=284697&r2=284698
==============================================================================
--- branches/1.8/doc/tex/asterisk.tex (original)
+++ branches/1.8/doc/tex/asterisk.tex Thu Sep 2 11:34:32 2010
@@ -151,6 +151,9 @@
\chapter{Secure Calls}
\input{secure-calls.tex}
+\chapter{Manipulating Party ID Information}
+ \input{partymanip.tex}
+
\chapter{Call Completion Supplementary Services}
\input{ccss.tex}
Modified: branches/1.8/doc/tex/channelvariables.tex
URL: http://svnview.digium.com/svn/asterisk/branches/1.8/doc/tex/channelvariables.tex?view=diff&rev=284698&r1=284697&r2=284698
==============================================================================
--- branches/1.8/doc/tex/channelvariables.tex (original)
+++ branches/1.8/doc/tex/channelvariables.tex Thu Sep 2 11:34:32 2010
@@ -1044,10 +1044,23 @@
${OSPOUTAUDIOQOS} The outbound call leg audio QoS string.
\end{verbatim}
-\subsection{Connected line 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}
-\end{verbatim}
+\subsection{Digit manipulation}
+\begin{verbatim}
+${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}
Added: branches/1.8/doc/tex/partymanip.tex
URL: http://svnview.digium.com/svn/asterisk/branches/1.8/doc/tex/partymanip.tex?view=auto&rev=284698
==============================================================================
--- branches/1.8/doc/tex/partymanip.tex (added)
+++ branches/1.8/doc/tex/partymanip.tex Thu Sep 2 11:34:32 2010
@@ -1,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}
Propchange: branches/1.8/doc/tex/partymanip.tex
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: branches/1.8/doc/tex/partymanip.tex
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: branches/1.8/doc/tex/partymanip.tex
------------------------------------------------------------------------------
svn:mime-type = text/plain
More information about the asterisk-commits
mailing list