1 files changed, 80 insertions, 0 deletions
diff --git a/trunk/doc/tex/localchannel.tex b/trunk/doc/tex/localchannel.tex
new file mode 100644
index 000000000..ab42606f7
--- /dev/null
+++ b/trunk/doc/tex/localchannel.tex
@@ -0,0 +1,80 @@
+\subsection{Introduction}
+
+chan\_local is a pseudo-channel. Use of this channel simply loops calls back
+into the dialplan in a different context. Useful for recursive routing.
+
+\subsection{Syntax}
+\begin{verbatim}
+ Local/extension@context[/{n|j}]
+\end{verbatim}
+
+Adding "/n" at the end of the string will make the Local channel not do a
+native transfer (the "n" stands for "n"o release) upon the remote end answering
+the line. This is an esoteric, but important feature if you expect the Local
+channel to handle calls exactly like a normal channel. If you do not have the
+"no release" feature set, then as soon as the destination (inside of the Local
+channel) answers the line and one audio frame passes, the variables and dial plan
+will revert back to that of the original call, and the Local channel will become a
+zombie and be removed from the active channels list. This is desirable in some
+circumstances, but can result in unexpected dialplan behavior if you are doing
+fancy things with variables in your call handling.
+
+There is another option that can be used with local channels, which is the "j"
+option.  The "j" option must be used with the "n" option to make sure that the
+local channel does not get optimized out of the call.  This option will enable
+a jitterbuffer on the local channel.  The jitterbuffer will be used to de-jitter
+audio that it receives from the channel that called the local channel.  This is
+especially in the case of putting chan\_local in between an incoming SIP call
+and Asterisk applications, so that the incoming audio will be de-jittered.
+
+\subsection{Purpose}
+
+The Local channel construct can be used to establish dialing into any part of
+the dialplan.
+
+Imagine you have a TE410P in your box. You want to do something for which you
+must use a Dial statement (for instance when dropping files in
+\path{/var/spool/outgoing}) but you do want to be able to use your dialplans
+least-cost-routes or other intelligent stuff. What you could do before we had
+chan\_local was create a cross-link between two ports of the TE410P and then
+Dial out one port and in the other. This way you could control where the call
+was going.
+
+Of course, this was a nasty hack, and to make it more sensible, chan\_local was
+built.
+
+The "Local" channel driver allows you to convert an arbitrary extension into a
+channel. It is used in a variety of places, including agents, etc.
+
+This also allows us to hop to contexts like a GoSub routine; See examples below.
+
+\subsection{Examples}
+\begin{astlisting}
+\begin{verbatim}
+[inbound] ; here falls all incoming calls
+exten => s,1,Answer
+exten => s,2,Dial(local/200@internal,30,r)
+exten => s,3,Playback(sorrynoanswer)
+exten => s,4,Hangup
+
+[internal] ; here where our phones falls for default
+exten => 200,1,Dial(sip/blah)
+exten => 200,102,VoiceMail(${EXTEN}@default)
+
+exten => 201,1,Dial(zap/1)
+exten => 201,102,VoiceMail(${EXTEN}@default)
+
+exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number
+\end{verbatim}
+\end{astlisting}
+
+\subsection{Caveats}
+
+If you use chan\_local from a call-file and you want to pass channel variables
+into your context, make sure you append the '/n', because otherwise
+chan\_local will 'optimize' itself out of the call-path, and the variables will
+get lost. i.e.
+
+\begin{verbatim}
+ Local/00531234567@pbx becomes Local/00531234567@pbx/n
+\end{verbatim}