diff options
Diffstat (limited to 'doc/tex/partymanip.tex')
| -rw-r--r-- | doc/tex/partymanip.tex | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/doc/tex/partymanip.tex b/doc/tex/partymanip.tex deleted file mode 100644 index 72a7469d2..000000000 --- a/doc/tex/partymanip.tex +++ /dev/null @@ -1,331 +0,0 @@ -\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. - -The 'i' option of the CONNECTEDLINE dialplan function should always be -used in the CONNECTED_LINE interception macros. The interception macro -always passes the connected line information on to the channel driver when -the macro exits. Similarly, the 'i' option of the REDIRECTING dialplan -function should always be used in the REDIRECTING interception macros. - -\begin{verbatim} -${REDIRECTING_CALLEE_SEND_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_CALLEE_SEND_MACRO_ARGS} - Arguments to pass to ${REDIRECTING_CALLEE_SEND_MACRO}. - -${REDIRECTING_CALLER_SEND_MACRO} - Macro to call before sending a redirecting update to the caller. -${REDIRECTING_CALLER_SEND_MACRO_ARGS} - Arguments to pass to ${REDIRECTING_CALLER_SEND_MACRO}. - -${CONNECTED_LINE_CALLEE_SEND_MACRO} - Macro to call before sending a connected line update to the callee. -${CONNECTED_LINE_CALLEE_SEND_MACRO_ARGS} - Arguments to pass to ${CONNECTED_LINE_CALLEE_SEND_MACRO}. - -${CONNECTED_LINE_CALLER_SEND_MACRO} - Macro to call before sending a connected line update to the caller. -${CONNECTED_LINE_CALLER_SEND_MACRO_ARGS} - Arguments to pass to ${CONNECTED_LINE_CALLER_SEND_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} |