mirror of https://github.com/asterisk/asterisk
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-fbb531ad65f310-digiumphones
Richard Mudgett
15 years ago
parent
172741bfcf
commit
df6d017aa1
@ -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}
|
||||
Loading…
Reference in new issue