Merged revisions 285710 via svnmerge from

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

........
  r285710 | bbryant | 2010-09-09 14:50:13 -0400 (Thu, 09 Sep 2010) | 8 lines
  
  Fixes an issue with dialplan pattern matching where the specificity for pattern ranges and pattern special characters was inconsistent.
  
  (closes issue #16903)
  Reported by: Nick_Lewis
  Patches: 
        pbx.c-specificity.patch uploaded by Nick Lewis (license 657)
  Tested by: Nick_Lewis
........


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.8@285711 f38db490-d61c-443f-a65b-d21fe96a405b

4 files changed, 429 insertions, 5 deletions

diff --git a/doc/tex/asterisk.tex b/doc/tex/asterisk.tex
index 4934d14fc..38d58bdef 100644
--- a/doc/tex/asterisk.tex
+++ b/doc/tex/asterisk.tex
@@ -151,12 +151,18 @@ 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}
 
 \chapter{Packet Loss Concealment}
   \input{plc.tex}
 
+\chapter{Sounds Packages}
+  \input{sounds.tex}
+
 \chapter{Development}
   \section{Backtrace}
   \input{backtrace.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}
diff --git a/doc/tex/sounds.tex b/doc/tex/sounds.tex
new file mode 100644
index 000000000..59091983b
--- /dev/null
+++ b/doc/tex/sounds.tex
@@ -0,0 +1,80 @@
+\section{Introduction}
+Asterisk utilizes a variety of sound prompts that are available in several file
+formats and languages. Multiple languages and formats can be installed on the 
+same system, and Asterisk will utilize prompts from languages installed, and 
+will automatically pick the least CPU intensive format that is available on the
+system (based on codecs in use, in additional to the codec and format modules
+installed and available).
+
+In addition to the prompts available with Asterisk, you can create your own sets
+of prompts and utilize them as well. This document will tell you how the prompts
+available for Asterisk are created so that the prompts you create can be as close
+and consistent in the quality and volume levels as those shipped with Asterisk.
+
+\section{Getting The Sounds Tools}
+The sounds tools are available in the publicly accessible repotools repository.
+You can check these tools out with Subversion via the following command:
+
+\begin{astlisting}
+\begin{verbatim}
+# svn co http://svn.asterisk.org/svn/repotools
+\end{verbatim}
+\end{astlisting}
+
+The sound tools are available in the subdirectory sound_tools/ which contains the
+following directories:
+
+\begin{itemize}
+\item audiofilter
+\item makeg722
+\item scripts
+\end{itemize}
+
+\section{About The Sounds Tools}
+The following sections will describe the sound tools in more detail and explain what
+they are used for in the sounds package creation process.
+
+\subsection{audiofilter}
+The audiofilter application is used to "tune" the sound files in such a way that
+they sound good when being used while in a compressed format. The values in the
+scripts for creating the sound files supplied in repotools is essentially a
+high-pass filter that drops out audio below 100Hz (or so).
+
+(There is an ITU specification that states for 8KHz audio that is being compressed
+frequencies below a certain threshold should be removed because they make the
+resulting compressed audio sound worse than it should.)
+
+The audiofilter application is used by the 'converter' script located in the
+scripts subdirectory of repotools/sound_tools. The values being passed to the
+audiofilter application is as follows:
+
+\begin{astlisting}
+\begin{verbatim}
+audiofilter -n 0.86916 -1.73829 0.86916 -d 1.00000 -1.74152 0.77536
+\end{verbatim}
+\end{astlisting}
+
+
+The two options -n and -d are 'numerator' and 'denominator'. Per the author,
+Jean-Marc Valin, "These values are filter coefficients (-n means numerator, -d is 
+denominator) expressed in the z-transform domain. There represent an elliptic filter
+that I designed with Octave such that 'the result sounds good'."
+
+\subsection{makeg722}
+The makeg722 application is used by the 'converters' script to generate the G.722
+sound files that are shipped with Asterisk. It starts with the RAW sound files and
+then converts them to G.722.
+
+\subsection{scripts}
+The scripts folder is where all the magic happens. These are the scripts that the
+Asterisk open source team use to build the packaged audio files for the various
+formats that are distributed with Asterisk.
+
+\begin{itemize}
+\item chkcore - used to check that the contents of core-sounds-$<$lang$>$.txt are in sync
+\item chkextra - same as above, but checks the extra sound files
+\item mkcore - script used to generate the core sounds packages
+\item mkextra - script used to generate the extra sounds packages
+\item mkmoh - script used to generate the music on hold packages
+\item converters - script used to convert the master files to various formats
+\end{itemize}