From df6d017aa1d4cadad20aa485c6810a6d8cf09749 Mon Sep 17 00:00:00 2001 From: Richard Mudgett Date: Thu, 2 Sep 2010 16:35:39 +0000 Subject: 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 --- doc/tex/asterisk.tex | 3 + doc/tex/channelvariables.tex | 23 ++- doc/tex/partymanip.tex | 325 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 346 insertions(+), 5 deletions(-) create mode 100644 doc/tex/partymanip.tex (limited to 'doc') 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} -- cgit v1.2.3