diff options
| author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-07-02 22:27:46 +0000 |
|---|---|---|
| committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-07-02 22:27:46 +0000 |
| commit | 3357366474ad27c72b2f26c759f85c5d34dbdc84 (patch) | |
| tree | 4c5b7a9ec6daf345dc48805fe38a7d941866ed93 /doc/tex | |
| parent | 9e3b3287a4eb9ae29bc9e3f808162f3382d404b6 (diff) | |
* Move LaTeX docs into a tex/ subdirectory of the doc/ dir
* Add a Makefile in doc/tex/ for generating PDF and HTML
* Add a README.txt file to doc/tex/ to document which tools are used and what
web sites to visit for getting them.
* Update build_tools/prep_tarball to put the proper Asterisk version string
in the automatically generated PDF for release tarballs
git-svn-id: http://svn.digium.com/svn/asterisk/trunk@72982 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'doc/tex')
38 files changed, 17168 insertions, 0 deletions
diff --git a/doc/tex/Makefile b/doc/tex/Makefile new file mode 100644 index 000000000..2ccf892d3 --- /dev/null +++ b/doc/tex/Makefile @@ -0,0 +1,35 @@ +include ../../makeopts + +pdf: asterisk.pdf + +asterisk.pdf: $(wildcard *.tex) +ifeq ($(findstring rubber,$(RUBBER)),) + @echo "**********************************************" + @echo "** You must install the \"rubber\" tool ***" + @echo "** to generate the Asterisk reference PDF. ***" + @echo "**********************************************" +else + @echo "**********************************************" + @echo "** The Asterisk reference PDF will now be ***" + @echo "** generated. When complete, it will be ***" + @echo "** located at asterisk.pdf. ***" + @echo "**********************************************" + @cp asterisk.tex asterisk.tex.orig + @sed -i -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex + @$(RUBBER) --pdf asterisk.tex + @mv asterisk.tex.orig asterisk.tex +endif + +html: + @echo "**********************************************" + @echo "** The Asterisk reference HTML will now be ***" + @echo "** generated. When complete, it will be ***" + @echo "** located in the asterisk/ directory. ***" + @echo "** Note that the latex2html tool is ***" + @echo "** required for this to work. ***" + @echo "**********************************************" + @cp asterisk.tex asterisk.tex.orig + @sed -i -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex + @latex2html asterisk.tex + @mv asterisk.tex.orig asterisk.tex + diff --git a/doc/tex/README.txt b/doc/tex/README.txt new file mode 100644 index 000000000..460d330a0 --- /dev/null +++ b/doc/tex/README.txt @@ -0,0 +1,24 @@ +Asterisk Reference Documentation +-------------------------------- + +1) To generate a PDF from this documentation, you will need the rubber tool, + and all of its dependencies. The web site for this tool is: + + http://www.pps.jussieu.fr/~beffara/soft/rubber/ + + Then, once this tool is installed, running "make pdf" will generate + the PDF automatically using this tool. The result will be asterisk.pdf. + + NOTE: After installing rubber, you will need to re-run the top level + configure script. It checks to see if rubber is installed, so that the + asterisk.pdf Makefile target can produce a useful error message when it is + not installed. + +2) To generate HTML from this documentation, you will need the latex2html tool, + and all of its dependencies. The web site for this tool is: + + http://www.latex2html.org/ + + Then, once this tool is installed, running "make html" will generate the + HTML documentation. The result will be an asterisk directory full of + HTML files. diff --git a/doc/tex/ael.tex b/doc/tex/ael.tex new file mode 100644 index 000000000..416b67e34 --- /dev/null +++ b/doc/tex/ael.tex @@ -0,0 +1,1268 @@ +\section{Introduction} + +AEL is a specialized language intended purely for +describing Asterisk dial plans. + +The current version was written by Steve Murphy, and is a rewrite of +the original version. + +This new version further extends AEL, and +provides more flexible syntax, better error messages, and some missing +functionality. + +AEL is really the merger of 4 different 'languages', or syntaxes: + +\begin{itemize} + \item The first and most obvious is the AEL syntax itself. A BNF is + provided near the end of this document. + + \item The second syntax is the Expression Syntax, which is normally + handled by Asterisk extension engine, as expressions enclosed in + \$[...]. The right hand side of assignments are wrapped in \$[ ... ] + by AEL, and so are the if and while expressions, among others. + + \item The third syntax is the Variable Reference Syntax, the stuff + enclosed in \${..} curly braces. It's a bit more involved than just + putting a variable name in there. You can include one of dozens of + 'functions', and their arguments, and there are even some string + manipulation notation in there. + + \item The last syntax that underlies AEL, and is not used + directly in AEL, is the Extension Language Syntax. The + extension language is what you see in extensions.conf, and AEL + compiles the higher level AEL language into extensions and + priorities, and passes them via function calls into + Asterisk. Embedded in this language is the Application/AGI + commands, of which one application call per step, or priority + can be made. You can think of this as a "macro assembler" + language, that AEL will compile into. +\end{itemize} + +Any programmer of AEL should be familiar with it's syntax, of course, +as well as the Expression syntax, and the Variable syntax. + + +\section{Asterisk in a Nutshell} + +Asterisk acts as a server. Devices involved in telephony, like Zapata +cards, or Voip phones, all indicate some context that should be +activated in their behalf. See the config file formats for IAX, SIP, +zapata.conf, etc. They all help describe a device, and they all +specify a context to activate when somebody picks up a phone, or a +call comes in from the phone company, or a voip phone, etc. + +\subsection{Contexts} + +Contexts are a grouping of extensions. + +Contexts can also include other contexts. Think of it as a sort of +merge operation at runtime, whereby the included context's extensions +are added to the contexts making the inclusion. + +\subsection{Extensions and priorities} + +A Context contains zero or more Extensions. There are several +predefined extensions. The "s" extension is the "start" extension, and +when a device activates a context the "s" extension is the one that is +going to be run. Other extensions are the timeout "t" extension, the +invalid response, or "i" extension, and there's a "fax" extension. For +instance, a normal call will activate the "s" extension, but an +incoming FAX call will come into the "fax" extension, if it +exists. (BTW, asterisk can tell it's a fax call by the little "beep" +that the calling fax machine emits every so many seconds.). + +Extensions contain several priorities, which are individual +instructions to perform. Some are as simple as setting a variable to a +value. Others are as complex as initiating the Voicemail application, +for instance. Priorities are executed in order. + +When the 's" extension completes, asterisk waits until the timeout for +a response. If the response matches an extension's pattern in the +context, then control is transferred to that extension. Usually the +responses are tones emitted when a user presses a button on their +phone. For instance, a context associated with a desk phone might not +have any "s" extension. It just plays a dialtone until someone starts +hitting numbers on the keypad, gather the number, find a matching +extension, and begin executing it. That extension might Dial out over +a connected telephone line for the user, and then connect the two +lines together. + +The extensions can also contain "goto" or "jump" commands to skip to +extensions in other contexts. Conditionals provide the ability to +react to different stimuli, and there you have it. + +\subsection{Macros} + +Think of a macro as a combination of a context with one nameless +extension, and a subroutine. It has arguments like a subroutine +might. A macro call can be made within an extension, and the +individual statements there are executed until it ends. At this point, +execution returns to the next statement after the macro call. Macros +can call other macros. And they work just like function calls. + +\subsection{Applications} + +Application calls, like "Dial()", or "Hangup()", or "Answer()", are +available for users to use to accomplish the work of the +dialplan. There are over 145 of them at the moment this was written, +and the list grows as new needs and wants are uncovered. Some +applications do fairly simple things, some provide amazingly complex +services. + +Hopefully, the above objects will allow you do anything you need to in +the Asterisk environment! + +\section{Getting Started} + +The AEL parser (pbx\_ael.so) is completely separate from the module +that parses extensions.conf (pbx\_config.so). To use AEL, the only +thing that has to be done is the module pbx\_ael.so must be loaded by +Asterisk. This will be done automatically if using 'autoload=yes' in +/etc/asterisk/modules.conf. When the module is loaded, it will look +for 'extensions.ael' in /etc/asterisk/. extensions.conf and +extensions.ael can be used in conjunction with +each other if that is what is desired. Some users may want to keep +extensions.conf for the features that are configured in the 'general' +section of extensions.conf. + +Reloading extensions.ael + +To reload extensions.ael, the following command can be issued at the +CLI: + + *CLI> ael reload + + +\section{Debugging} + +Right at this moment, the following commands are available, but do +nothing: + +Enable AEL contexts debug + *CLI> ael debug contexts + +Enable AEL macros debug + *CLI> ael debug macros + +Enable AEL read debug + *CLI> ael debug read + +Enable AEL tokens debug + *CLI> ael debug tokens + +Disable AEL debug messages + *CLI> ael no debug + +If things are going wrong in your dialplan, you can use the following +facilities to debug your file: + +1. The messages log in /var/log/asterisk. (from the checks done at load time). +2. the "show dialplan" command in asterisk +3. the standalone executable, "aelparse" built in the utils/ dir in the source. + + +\section{About "aelparse"} + +You can use the "aelparse" program to check your extensions.ael +file before feeding it to asterisk. Wouldn't it be nice to eliminate +most errors before giving the file to asterisk? + +aelparse is compiled in the utils directory of the asterisk release. +It isn't installed anywhere (yet). You can copy it to your favorite +spot in your PATH. + +aelparse has two optional arguments: + +\begin{itemize} + \item -d + \begin{itemize} + \item Override the normal location of the config file dir, (usually + /etc/asterisk), and use the current directory instead as the + config file dir. Aelparse will then expect to find the file + "./extensions.ael" in the current directory, and any included + files in the current directory as well. + \end{itemize} + \item -n + \begin{itemize} + \item don't show all the function calls to set priorities and contexts + within asterisk. It will just show the errors and warnings from + the parsing and semantic checking phases. + \end{itemize} +\end{itemize} + +\section{General Notes about Syntax} + +Note that the syntax and style are now a little more free-form. The +opening '{' (curly-braces) do not have to be on the same line as the +keyword that precedes them. Statements can be split across lines, as +long as tokens are not broken by doing so. More than one statement can +be included on a single line. Whatever you think is best! + +You can just as easily say, + +\begin{verbatim} +if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } +\end{verbatim} + +as you can say: + +\begin{verbatim} +if(${x}=1) +{ + NoOp(hello!); + goto s|3; +} +else +{ + NoOp(Goodbye!); + goto s|12; +} +\end{verbatim} + +or: + +\begin{verbatim} +if(${x}=1) { + NoOp(hello!); + goto s|3; +} else { + NoOp(Goodbye!); + goto s|12; +} +\end{verbatim} + +or: + +\begin{verbatim} +if (${x}=1) { + NoOp(hello!); goto s|3; +} else { + NoOp(Goodbye!); goto s|12; +} +\end{verbatim} + +\section{Keywords} + +The AEL keywords are case-sensitive. If an application name and a +keyword overlap, there is probably good reason, and you should +consider replacing the application call with an AEL statement. If you +do not wish to do so, you can still use the application, by using a +capitalized letter somewhere in its name. In the Asterisk extension +language, application names are NOT case-sensitive. + +The following are keywords in the AEL language: +\begin{itemize} + \item abstract + \item context + \item macro + \item globals + \item ignorepat + \item switch + \item if + \item ifTime + \item else + \item random + \item goto + \item jump + \item local + \item return + \item break + \item continue + \item regexten + \item hint + \item for + \item while + \item case + \item pattern + \item default NOTE: the "default" keyword can be used as a context name, + for those who would like to do so. + \item catch + \item switches + \item eswitches + \item includes +\end{itemize} + + +\section{Procedural Interface and Internals} + +AEL first parses the extensions.ael file into a memory structure representing the file. +The entire file is represented by a tree of "pval" structures linked together. + +This tree is then handed to the semantic check routine. + +Then the tree is handed to the compiler. + +After that, it is freed from memory. + +A program could be written that could build a tree of pval structures, and +a pretty printing function is provided, that would dump the data to a file, +or the tree could be handed to the compiler to merge the data into the +asterisk dialplan. The modularity of the design offers several opportunities +for developers to simplify apps to generate dialplan data. + + +\subsection{AEL version 2 BNF} + +(hopefully, something close to bnf). + +First, some basic objects + +\begin{verbatim} +------------------------ +<word> a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]* + +<word3-list> a concatenation of up to 3 <word>s. + +<collected-word> all characters encountered until the character that follows the <collected-word> in the grammar. +------------------------- + +<file> :== <objects> + +<objects> :== <object> + | <objects> <object> + + +<object> :== <context> + | <macro> + | <globals> + | ';' + + +<context> :== 'context' <word> '{' <elements> '}' + | 'context' <word> '{' '}' + | 'context' 'default' '{' <elements> '}' + | 'context' 'default' '{' '}' + | 'abstract' 'context' <word> '{' <elements> '}' + | 'abstract' 'context' <word> '{' '}' + | 'abstract' 'context' 'default' '{' <elements> '}' + | 'abstract' 'context' 'default' '{' '}' + + +<macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}' + | 'macro' <word> '(' <arglist> ')' '{' '}' + | 'macro' <word> '(' ')' '{' <macro_statements> '}' + | 'macro' <word> '(' ')' '{' '}' + + +<globals> :== 'globals' '{' <global_statements> '}' + | 'globals' '{' '}' + + +<global_statements> :== <global_statement> + | <global_statements> <global_statement> + + +<global_statement> :== <word> '=' <collected-word> ';' + + +<arglist> :== <word> + | <arglist> ',' <word> + + +<elements> :== <element> + | <elements> <element> + + +<element> :== <extension> + | <includes> + | <switches> + | <eswitches> + | <ignorepat> + | <word> '=' <collected-word> ';' + | 'local' <word> '=' <collected-word> ';' + | ';' + + +<ignorepat> :== 'ignorepat' '=>' <word> ';' + + +<extension> :== <word> '=>' <statement> + | 'regexten' <word> '=>' <statement> + | 'hint' '(' <word3-list> ')' <word> '=>' <statement> + | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement> + + +<statements> :== <statement> + | <statements> <statement> + +<if_head> :== 'if' '(' <collected-word> ')' + +<random_head> :== 'random' '(' <collected-word> ')' + +<ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + + +<word3-list> :== <word> + | <word> <word> + | <word> <word> <word> + +<switch_head> :== 'switch' '(' <collected-word> ')' '{' + + +<statement> :== '{' <statements> '}' + | <word> '=' <collected-word> ';' + | 'local' <word> '=' <collected-word> ';' + | 'goto' <target> ';' + | 'jump' <jumptarget> ';' + | <word> ':' + | 'for' '(' <collected-word> ';' <collected-word> ';' <collected-word> ')' <statement> + | 'while' '(' <collected-word> ')' <statement> + | <switch_head> '}' + | <switch_head> <case_statements> '}' + | '&' macro_call ';' + | <application_call> ';' + | <application_call> '=' <collected-word> ';' + | 'break' ';' + | 'return' ';' + | 'continue' ';' + | <random_head> <statement> + | <random_head> <statement> 'else' <statement> + | <if_head> <statement> + | <if_head> <statement> 'else' <statement> + | <ifTime_head> <statement> + | <ifTime_head> <statement> 'else' <statement> + | ';' + +<target> :== <word> + | <word> '|' <word> + | <word> '|' <word> '|' <word> + | 'default' '|' <word> '|' <word> + | <word> ',' <word> + | <word> ',' <word> ',' <word> + | 'default' ',' <word> ',' <word> + +<jumptarget> :== <word> + | <word> ',' <word> + | <word> ',' <word> '@' <word> + | <word> '@' <word> + | <word> ',' <word> '@' 'default' + | <word> '@' 'default' + +<macro_call> :== <word> '(' <eval_arglist> ')' + | <word> '(' ')' + +<application_call_head> :== <word> '(' + +<application_call> :== <application_call_head> <eval_arglist> ')' + | <application_call_head> ')' + +<eval_arglist> :== <collected-word> + | <eval_arglist> ',' <collected-word> + | /* nothing */ + | <eval_arglist> ',' /* nothing */ + +<case_statements> :== <case_statement> + | <case_statements> <case_statement> + + +<case_statement> :== 'case' <word> ':' <statements> + | 'default' ':' <statements> + | 'pattern' <word> ':' <statements> + | 'case' <word> ':' + | 'default' ':' + | 'pattern' <word> ':' + +<macro_statements> :== <macro_statement> + | <macro_statements> <macro_statement> + +<macro_statement> :== <statement> + | 'catch' <word> '{' <statements> '}' + +<switches> :== 'switches' '{' <switchlist> '}' + | 'switches' '{' '}' + +<eswitches> :== 'eswitches' '{' <switchlist> '}' + | 'eswitches' '{' '}' + +<switchlist> :== <word> ';' + | <switchlist> <word> ';' + +<includeslist> :== <includedname> ';' + | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> ';' + | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + +<includedname> :== <word> + | 'default' + +<includes> :== 'includes' '{' <includeslist> '}' + | 'includes' '{' '}' + +\end{verbatim} + + +\section{AEL Example USAGE} + +\subsection{Comments} + +Comments begin with // and end with the end of the line. + +Comments are removed by the lexical scanner, and will not be +recognized in places where it is busy gathering expressions to wrap in +\$[] , or inside application call argument lists. The safest place to put +comments is after terminating semicolons, or on otherwise empty lines. + + +\subsection{Context} + +Contexts in AEL represent a set of extensions in the same way that +they do in extensions.conf. + +\begin{verbatim} +context default { + +} + + +A context can be declared to be "abstract", in which case, this +declaration expresses the intent of the writer, that this context will +only be included by another context, and not "stand on its own". The +current effect of this keyword is to prevent "goto " statements from +being checked. + +\begin{verbatim} +abstract context longdist { + _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); +} +\end{verbatim} + + +\subsection{Extensions} + +To specify an extension in a context, the following syntax is used. If +more than one application is be called in an extension, they can be +listed in order inside of a block. + +\begin{verbatim} +context default { + 1234 => Playback(tt-monkeys); + 8000 => { + NoOp(one); + NoOp(two); + NoOp(three); + }; + _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} + +Two optional items have been added to the AEL syntax, that allow the +specification of hints, and a keyword, regexten, that will force the +numbering of priorities to start at 2. + +The ability to make extensions match by CID is preserved in +AEL; just use '/' and the CID number in the specification. See below. + +\begin{verbatim} +context default { + + regexten _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} + +\begin{verbatim} +context default { + + hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} + +\begin{verbatim} +context default { + + regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} + +The regexten must come before the hint if they are both present. + +CID matching is done as with the extensions.conf file. Follow the extension +name/number with a slash (/) and the number to match against the Caller ID: + +\begin{verbatim} +context zoombo +{ + 819/7079953345 => { NoOp(hello, 3345); } +} +\end{verbatim} + +In the above, the 819/7079953345 extension will only be matched if the +CallerID is 7079953345, and the dialed number is 819. Hopefully you have +another 819 extension defined for all those who wish 819, that are not so lucky +as to have 7079953345 as their CallerID! + + +\subsection{Includes} + +Contexts can be included in other contexts. All included contexts are +listed within a single block. + +\begin{verbatim} +context default { + includes { + local; + longdistance; + international; + } +} +\end{verbatim} + +Time-limited inclusions can be specified, as in extensions.conf +format, with the fields described in the wiki page Asterisk cmd +GotoIfTime. + +\begin{verbatim} +context default { + includes { + local; + longdistance|16:00-23:59|mon-fri|*|*; + international; + } +} +\end{verbatim} + +\subsection{\#include} + +You can include other files with the \#include "filepath" construct. + +\begin{verbatim} + #include "/etc/asterisk/testfor.ael" +\end{verbatim} + +An interesting property of the \#include, is that you can use it almost +anywhere in the .ael file. It is possible to include the contents of +a file in a macro, context, or even extension. The \#include does not +have to occur at the beginning of a line. Included files can include +other files, up to 50 levels deep. If the path provided in quotes is a +relative path, the parser looks in the config file directory for the +file (usually /etc/asterisk). + + + +\subsection{Dialplan Switches} + +Switches are listed in their own block within a context. For clues as +to what these are used for, see Asterisk - dual servers, and Asterisk +config extensions.conf. + +\begin{verbatim} +context default { + switches { + DUNDi/e164; + IAX2/box5; + }; + eswitches { + IAX2/context@${CURSERVER}; + } +} +\end{verbatim} + + +\subsection{Ignorepat} + +ignorepat can be used to instruct channel drivers to not cancel +dialtone upon receipt of a particular pattern. The most commonly used +example is '9'. + +\begin{verbatim} +context outgoing { + ignorepat => 9; +} +\end{verbatim} + + +\subsection{Variables} + +Variables in Asterisk do not have a type, so to define a variable, it +just has to be specified with a value. + +Global variables are set in their own block. + +\begin{verbatim} +globals { + CONSOLE=Console/dsp; + TRUNK=Zap/g2; +} +\end{verbatim} + + +Variables can be set within extensions as well. + +\begin{verbatim} +context foo { + 555 => { + x=5; + y=blah; + divexample=10/2 + NoOp(x is ${x} and y is ${y} !); + } +} +\end{verbatim} + +NOTE: AEL wraps the right hand side of an assignment with \$[ ] to allow +expressions to be used If this is unwanted, you can protect the right hand +side from being wrapped by using the Set() application. +Read the README.variables about the requirements and behavior +of \$[ ] expressions. + +NOTE: These things are wrapped up in a \$[ ] expression: The while() test; +the if() test; the middle expression in the for( x; y; z) statement +(the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b]) + +Writing to a dialplan function is treated the same as writing to a variable. + +\begin{verbatim} +context blah { + s => { + CALLERID(name)=ChickenMan; + NoOp(My name is ${CALLERID(name)} !); + } +} +\end{verbatim} + +You can declare variables in Macros, as so: + +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + Myvar=1; + NoOp(Myvar is set to ${myvar}); +} +\end{verbatim} + +\subsection{Local Variables} + +In 1.2, and 1.4, ALL VARIABLES are CHANNEL variables, including the function +arguments and associated ARG1, ARG2, etc variables. Sorry. + +In trunk (1.6 and higher), we have made all arguments local variables to +a macro call. They will not affect channel variables of the same name. +This includes the ARG1, ARG2, etc variables. + +Users can declare their own local variables by using the keyword 'local' +before setting them to a value; + +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + local Myvar=1; + NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); +} +\end{verbatim} + +In the above example, Myvar, firstarg, and secondarg are all local variables, +and will not be visible to the calling code, be it an extension, or another Macro. + +If you need to make a local variable within the Set() application, you can do it this way: + +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + Set(LOCAL(Myvar)=1); + NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); +} +\end{verbatim} + + +\subsection{Loops} + +AEL has implementations of 'for' and 'while' loops. + +\begin{verbatim} +context loops { + 1 => { + for (x=0; ${x} < 3; x=${x} + 1) { + Verbose(x is ${x} !); + } + } + 2 => { + y=10; + while (${y} >= 0) { + Verbose(y is ${y} !); + y=${y}-1; + } + } +} +\end{verbatim} + +NOTE: The conditional expression (the "\${y} >= 0" above) is wrapped in + \$[ ] so it can be evaluated. NOTE: The for loop test expression + (the "\${x} < 3" above) is wrapped in \$[ ] so it can be evaluated. + + + +\subsection{Conditionals} + +AEL supports if and switch statements, like AEL, but adds ifTime, and +random. Unlike the original AEL, though, you do NOT need to put curly +braces around a single statement in the "true" branch of an if(), the +random(), or an ifTime() statement. The if(), ifTime(), and random() +statements allow optional else clause. + +\begin{verbatim} +context conditional { + _8XXX => { + Dial(SIP/${EXTEN}); + if ("${DIALSTATUS}" = "BUSY") + { + NoOp(yessir); + Voicemail(${EXTEN}|b); + } + else + Voicemail(${EXTEN}|u); + ifTime (14:00-25:00|sat-sun|*|*) + Voicemail(${EXTEN}|b); + else + { + Voicemail(${EXTEN}|u); + NoOp(hi, there!); + } + random(51) NoOp(This should appear 51% of the time); + + random( 60 ) + { + NoOp( This should appear 60% of the time ); + } + else + { + random(75) + { + NoOp( This should appear 30% of the time! ); + } + else + { + NoOp( This should appear 10% of the time! ); + } + } + } + _777X => { + switch (${EXTEN}) { + case 7771: + NoOp(You called 7771!); + break; + case 7772: + NoOp(You called 7772!); + break; + case 7773: + NoOp(You called 7773!); + // fall thru- + pattern 777[4-9]: + NoOp(You called 777 something!); + default: + NoOp(In the default clause!); + } + } +} +\end{verbatim} + +NOTE: The conditional expression in if() statements (the + "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in + \$[] for evaluation. + +NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can + be constants, or \${var} type references only. + +NOTE: AEL generates each case as a separate extension. case clauses + with no terminating 'break', or 'goto', have a goto inserted, to + the next clause, which creates a 'fall thru' effect. + +NOTE: AEL introduces the ifTime keyword/statement, which works just + like the if() statement, but the expression is a time value, + exactly like that used by the application GotoIfTime(). See + Asterisk cmd GotoIfTime + +NOTE: The pattern statement makes sure the new extension that is + created has an '\_' preceding it to make sure asterisk recognizes + the extension name as a pattern. + +NOTE: Every character enclosed by the switch expression's parenthesis + are included verbatim in the labels generated. So watch out for + spaces! + +NOTE: NEW: Previous to version 0.13, the random statement used the + "Random()" application, which has been deprecated. It now uses + the RAND() function instead, in the GotoIf application. + + +\subsection{Break, Continue, and Return} + +Three keywords, break, continue, and return, are included in the +syntax to provide flow of control to loops, and switches. + +The break can be used in switches and loops, to jump to the end of the +loop or switch. + +The continue can be used in loops (while and for) to immediately jump +to the end of the loop. In the case of a for loop, the increment and +test will then be performed. In the case of the while loop, the +continue will jump to the test at the top of the loop. + +The return keyword will cause an immediate jump to the end of the +context, or macro, and can be used anywhere. + + + +\subsection{goto, jump, and labels} + +This is an example of how to do a goto in AEL. + +\begin{verbatim} +context gotoexample { + s => { +begin: + NoOp(Infinite Loop! yay!); + Wait(1); + goto begin; // go to label in same extension + } + 3 => { + goto s|begin; // go to label in different extension + } + 4 => { + goto gotoexample|s|begin; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + goto gotoexample|s|begin; // go to label in different context + } +} +\end{verbatim} + +You can use the special label of "1" in the goto and jump +statements. It means the "first" statement in the extension. I would +not advise trying to use numeric labels other than "1" in goto's or +jumps, nor would I advise declaring a "1" label anywhere! As a matter +of fact, it would be bad form to declare a numeric label, and it might +conflict with the priority numbers used internally by asterisk. + +The syntax of the jump statement is: jump +extension[,priority][@context] If priority is absent, it defaults to +"1". If context is not present, it is assumed to be the same as that +which contains the "jump". + +\begin{verbatim} +context gotoexample { + s => { +begin: + NoOp(Infinite Loop! yay!); + Wait(1); + jump s; // go to first extension in same extension + } + 3 => { + jump s,begin; // go to label in different extension + } + 4 => { + jump s,begin@gotoexample; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + jump s@gotoexample; // go to label in different context + } +} +\end{verbatim} + +NOTE: goto labels follow the same requirements as the Goto() + application, except the last value has to be a label. If the + label does not exist, you will have run-time errors. If the + label exists, but in a different extension, you have to specify + both the extension name and label in the goto, as in: goto s|z; + if the label is in a different context, you specify + context|extension|label. There is a note about using goto's in a + switch statement below... + +NOTE AEL introduces the special label "1", which is the beginning + context number for most extensions. + +NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to + separate the items in the target address. You can't have a mix, + though, of '|' and ',' in the target. It's either one, or the other. + + + + +\subsection{Macros} + +A macro is defined in its own block like this. The arguments to the +macro are specified with the name of the macro. They are then referred +to by that same name. A catch block can be specified to catch special +extensions. + +\begin{verbatim} +macro std-exten( ext , dev ) { + Dial(${dev}/${ext},20); + switch(${DIALSTATUS) { + case BUSY: + Voicemail(b${ext}); + break; + default: + Voicemail(u${ext}); + + } + catch a { + VoiceMailMain(${ext}); + return; + } +} +\end{verbatim} + +A macro is then called by preceding the macro name with an +ampersand. Empty arguments can be passed simply with nothing between +comments(0.11). + +\begin{verbatim} +context example { + _5XXX => &std-exten(${EXTEN}, "IAX2"); + _6XXX => &std-exten(, "IAX2"); + _7XXX => &std-exten(${EXTEN},); + _8XXX => &std-exten(,); +} +\end{verbatim} + + +\section{Examples} + +\begin{verbatim} +context demo { + s => { + Wait(1); + Answer(); + TIMEOUT(digit)=5; + TIMEOUT(response)=10; +restart: + Background(demo-congrats); +instructions: + for (x=0; ${x} < 3; x=${x} + 1) { + Background(demo-instruct); + WaitExten(); + } + } + 2 => { + Background(demo-moreinfo); + goto s|instructions; + } + 3 => { + LANGUAGE()=fr; + goto s|restart; + } + + 500 => { + Playback(demo-abouttotry); + Dial(IAX2/guest@misery.digium.com); + Playback(demo-nogo); + goto s|instructions; + } + 600 => { + Playback(demo-echotest); + Echo(); + Playback(demo-echodone); + goto s|instructions; + } + # => { +hangup: + Playback(demo-thanks); + Hangup(); + } + t => goto #|hangup; + i => Playback(invalid); +} +\end{verbatim} + + +\section{Semantic Checks} + + +AEL, after parsing, but before compiling, traverses the dialplan +tree, and makes several checks: + +\begin{itemize} + \item Macro calls to non-existent macros. + \item Macro calls to contexts. + \item Macro calls with argument count not matching the definition. + \item application call to macro. (missing the '\&') + \item application calls to "GotoIf", "GotoIfTime", "while", + "endwhile", "Random", and "execIf", will generate a message to + consider converting the call to AEL goto, while, etc. constructs. + \item goto a label in an empty extension. + \item goto a non-existent label, either a within-extension, + within-context, or in a different context, or in any included + contexts. Will even check "sister" context references. + \item All the checks done on the time values in the dial plan, are + done on the time values in the ifTime() and includes times: + o the time range has to have two times separated by a dash; + o the times have to be in range of 0 to 24 hours. + o The weekdays have to match the internal list, if they are provided; + o the day of the month, if provided, must be in range of 1 to 31; + o the month name or names have to match those in the internal list. + \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler + will wrap it again, a warning is issued. + \item (0.5) If an expression had operators (you know, + +,-,*,/,%,!,etc), but no \${ } variables, a warning is + issued. Maybe someone forgot to wrap a variable name? + \item (0.12) check for duplicate context names. + \item (0.12) check for abstract contexts that are not included by any context. + \item (0.13) Issue a warning if a label is a numeric value. +\end{itemize} + +There are a subset of checks that have been removed until the proposed +AAL (Asterisk Argument Language) is developed and incorporated into Asterisk. +These checks will be: + +\begin{itemize} + \item (if the application argument analyzer is working: the presence + of the 'j' option is reported as error. + \item if options are specified, that are not available in an + application. + \item if you specify too many arguments to an application. + \item a required argument is not present in an application call. + \item Switch-case using "known" variables that applications set, that + does not cover all the possible values. (a "default" case will + solve this problem. Each "unhandled" value is listed. + \item a Switch construct is used, which is uses a known variable, and + the application that would set that variable is not called in + the same extension. This is a warning only... + \item Calls to applications not in the "applist" database (installed + in /var/lib/asterisk/applist" on most systems). + \item In an assignment statement, if the assignment is to a function, + the function name used is checked to see if it one of the + currently known functions. A warning is issued if it is not. +\end{itemize} + + +Differences with the original version of AEL +============================================ + +\begin{enumerate} + \item The \$[...] expressions have been enhanced to include the ==, ||, + and \&\& operators. These operators are exactly equivalent to the + =, |, and \& operators, respectively. Why? So the C, Java, C++ + hackers feel at home here. + \item It is more free-form. The newline character means very little, + and is pulled out of the white-space only for line numbers in + error messages. + \item It generates more error messages -- by this I mean that any + difference between the input and the grammar are reported, by + file, line number, and column. + \item It checks the contents of \$[ ] expressions (or what will end up + being \$[ ] expressions!) for syntax errors. It also does + matching paren/bracket counts. + \item It runs several semantic checks after the parsing is over, but + before the compiling begins, see the list above. + \item It handles \#include "filepath" directives. -- ALMOST + anywhere, in fact. You could easily include a file in a context, + in an extension, or at the root level. Files can be included in + files that are included in files, down to 50 levels of hierarchy... + \item Local Goto's inside Switch statements automatically have the + extension of the location of the switch statement appended to them. + \item A pretty printer function is available within pbx\_ael.so. + \item In the utils directory, two standalone programs are supplied for + debugging AEL files. One is called "aelparse", and it reads in + the /etc/asterisk/extensions.ael file, and shows the results of + syntax and semantic checking on stdout, and also shows the + results of compilation to stdout. The other is "aelparse1", + which uses the original ael compiler to do the same work, + reading in "/etc/asterisk/extensions.ael", using the original + 'pbx\_ael.so' instead. + \item AEL supports the "jump" statement, and the "pattern" statement + in switch constructs. Hopefully these will be documented in the + AEL README. + \item Added the "return" keyword, which will jump to the end of an + extension/Macro. + \item Added the ifTime (<time range>|<days of week>|<days of + month>|<months> ) {} [else {}] construct, which executes much + like an if () statement, but the decision is based on the + current time, and the time spec provided in the ifTime. See the + example above. (Note: all the other time-dependent Applications + can be used via ifTime) + \item Added the optional time spec to the contexts in the includes + construct. See examples above. + \item You don't have to wrap a single "true" statement in curly + braces, as in the original AEL. An "else" is attached to the + closest if. As usual, be careful about nested if statements! + When in doubt, use curlies! + \item Added the syntax [regexten] [hint(channel)] to precede an + extension declaration. See examples above, under + "Extension". The regexten keyword will cause the priorities in + the extension to begin with 2 instead of 1. The hint keyword + will cause its arguments to be inserted in the extension under + the hint priority. They are both optional, of course, but the + order is fixed at the moment-- the regexten must come before the + hint, if they are both present. + \item Empty case/default/pattern statements will "fall thru" as + expected. (0.6) + \item A trailing label in an extension, will automatically have a + NoOp() added, to make sure the label exists in the extension on + Asterisk. (0.6) + \item (0.9) the semicolon is no longer required after a closing brace! + (i.e. "];" ===> "\}". You can have them there if you like, but + they are not necessary. Someday they may be rejected as a syntax + error, maybe. + \item (0.9) the // comments are not recognized and removed in the + spots where expressions are gathered, nor in application call + arguments. You may have to move a comment if you get errors in + existing files. + \item (0.10) the random statement has been added. Syntax: random ( + <expr> ) <lucky-statement> [ else <unlucky-statement> ]. The + probability of the lucky-statement getting executed is <expr>, + which should evaluate to an integer between 0 and 100. If the + <lucky-statement> isn't so lucky this time around, then the + <unlucky-statement> gets executed, if it is present. +\end{enumerate} + + +\section{Hints and Bugs} + + The safest way to check for a null strings is to say \$[ "\${x}" = + "" ] The old way would do as shell scripts often do, and append + something on both sides, like this: \$[ \${x}foo = foo ]. The + trouble with the old way, is that, if x contains any spaces, then + problems occur, usually syntax errors. It is better practice and + safer wrap all such tests with double quotes! Also, there are now + some functions that can be used in a variable reference, + ISNULL(), and LEN(), that can be used to test for an empty string: + \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ]. + + Assignment vs. Set(). Keep in mind that setting a variable to + value can be done two different ways. If you choose say 'x=y;', + keep in mind that AEL will wrap the right-hand-side with + \$[]. So, when compiled into extension language format, the end + result will be 'Set(x=\$[y])'. If you don't want this effect, + then say "Set(x=y);" instead. + + +\section{The Full Power of AEL} + +A newcomer to Asterisk will look at the above constructs and +descriptions, and ask, "Where's the string manipulation functions?", +"Where's all the cool operators that other languages have to offer?", +etc. + +The answer is that the rich capabilities of Asterisk are made +available through AEL, via: + +\begin{itemize} + \item Applications: See Asterisk - documentation of application + commands + + \item Functions: Functions were implemented inside \${ .. } variable + references, and supply many useful capabilities. + + \item Expressions: An expression evaluation engine handles items + wrapped inside \$[...]. This includes some string manipulation + facilities, arithmetic expressions, etc. + + \item Application Gateway Interface: Asterisk can fork external + processes that communicate via pipe. AGI applications can be + written in any language. Very powerful applications can be added + this way. + + \item Variables: Channels of communication have variables associated + with them, and asterisk provides some global variables. These can be + manipulated and/or consulted by the above mechanisms. +\end{itemize} diff --git a/doc/tex/ajam.tex b/doc/tex/ajam.tex new file mode 100644 index 000000000..b5e184931 --- /dev/null +++ b/doc/tex/ajam.tex @@ -0,0 +1,85 @@ +\section{Asynchronous Javascript Asterisk Manger (AJAM)} + +AJAM is a new technology which allows web browsers or other HTTP enabled +applications and web pages to directly access the Asterisk Manger +Interface (AMI) via HTTP. Setting up your server to process AJAM +involves a few steps: + +\subsection{Setup the Asterisk HTTP server} + +\begin{enumerate} +\item Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable + Asterisk's builtin micro HTTP server. + +\item If you want Asterisk to actually deliver simple HTML pages, CSS, + javascript, etc. you should uncomment "enablestatic=yes" + +\item Adjust your "bindaddr" and "bindport" settings as appropriate for + your desired accessibility + +\item Adjust your "prefix" if appropriate, which must be the beginning of + any URI on the server to match. The default is "asterisk" and the + rest of these instructions assume that value. +\end{enumerate} + +\subsection{Allow Manager Access via HTTP} + +\begin{enumerate} +\item Make sure you have both "enabled = yes" and "webenabled = yes" setup + in /etc/asterisk/manager.conf + +\item You may also use "httptimeout" to set a default timeout for HTTP + connections. + +\item Make sure you have a manager username/secret +\end{enumerate} + +Once those configurations are complete you can reload or restart +Asterisk and you should be able to point your web browser to specific +URI's which will allow you to access various web functions. A complete +list can be found by typing "show http" at the Asterisk CLI. + +examples: + +http://localhost:8088/asterisk/manager?action=login\&username=foo\&secret=bar + +This logs you into the manager interface's "HTML" view. Once you're +logged in, Asterisk stores a cookie on your browser (valid for the +length of httptimeout) which is used to connect to the same session. + +http://localhost:8088/asterisk/rawman?action=status + +Assuming you've already logged into manager, this URI will give you a +"raw" manager output for the "status" command. + +http://localhost:8088/asterisk/mxml?action=status + +This will give you the same status view but represented as AJAX data, +theoretically compatible with RICO (http://www.openrico.org). + +http://localhost:8088/asterisk/static/ajamdemo.html + +If you have enabled static content support and have done a make install, +Asterisk will serve up a demo page which presents a live, but very +basic, "astman" like interface. You can login with your username/secret +for manager and have a basic view of channels as well as transfer and +hangup calls. It's only tested in Firefox, but could probably be made +to run in other browsers as well. + +A sample library (astman.js) is included to help ease the creation of +manager HTML interfaces. + +Note that for the demo, there is no need for *any* external web server. + +\subsection{Integration with other web servers} + +Asterisk's micro HTTP server is *not* designed to replace a general +purpose web server and it is intentionally created to provide only the +minimal interfaces required. Even without the addition of an external +web server, one can use Asterisk's interfaces to implement screen pops +and similar tools pulling data from other web servers using iframes, +div's etc. If you want to integrate CGI's, databases, PHP, etc. you +will likely need to use a more traditional web server like Apache and +link in your Asterisk micro HTTP server with something like this: + +ProxyPass /asterisk http://localhost:8088/asterisk diff --git a/doc/tex/app-sms.tex b/doc/tex/app-sms.tex new file mode 100644 index 000000000..b588761d8 --- /dev/null +++ b/doc/tex/app-sms.tex @@ -0,0 +1,491 @@ +\section{Introduction} + + The SMS module for Asterisk was developed by Adrian Kennard, and is an + implementation of the ETSI specification for landline SMS, ETSI ES 201 + 912, which is available from www.etsi.org. Landline SMS is starting to + be available in various parts of Europe, and is available from BT in + the UK. However, Asterisk would allow gateways to be created in other + locations such as the US, and use of SMS capable phones such as the + Magic Messenger. SMS works using analogue or ISDN lines. + +\section{Background} + + Short Message Service (SMS), or texting is very popular between mobile + phones. A message can be sent between two phones, and normally + contains 160 characters. There are ways in which various types of data + can be encoded in a text message such as ring tones, and small + graphic, etc. Text messaging is being used for voting and + competitions, and also SPAM... + + Sending a message involves the mobile phone contacting a message + centre (SMSC) and passing the message to it. The message centre then + contacts the destination mobile to deliver the message. The SMSC is + responsible for storing the message and trying to send it until the + destination mobile is available, or a timeout. + + Landline SMS works in basically the same way. You would normally have + a suitable text capable landline phone, or a separate texting box such + as a Magic Messenger on your phone line. This sends a message to a + message centre your telco provides by making a normal call and sending + the data using 1200 Baud FSK signaling according to the ETSI spec. To + receive a message the message centre calls the line with a specific + calling number, and the text capable phone answers the call and + receives the data using 1200 Baud FSK signaling. This works + particularly well in the UK as the calling line identity is sent + before the first ring, so no phones in the house would ring when a + message arrives. + +\section{Typical use with Asterisk} + + Sending messages from an Asterisk box can be used for a variety of + reasons, including notification from any monitoring systems, email + subject lines, etc. + + Receiving messages to an Asterisk box is typically used just to email + the messages to someone appropriate - we email and texts that are + received to our direct numbers to the appropriate person. Received + messages could also be used to control applications, manage + competitions, votes, post items to IRC, anything. + + Using a terminal such as a magic messenger, an Asterisk box could ask + as a message centre sending messages to the terminal, which will beep + and pop up the message (and remember 100 or so messages in its + memory). + +\section{Terminology} + +\begin{itemize} + \item SMS - + Short Message Service + i.e. text messages + + \item SMSC - + Short Message Service Centre + The system responsible for storing and forwarding messages + + \item MO - + Mobile Originated + A message on its way from a mobile or landline device to the SMSC + + \item MT - + Mobile Terminated + A message on its way from the SMSC to the mobile or landline device + + \item RX - + Receive + A message coming in to the Asterisk box + + \item TX - + Transmit + A message going out of the Asterisk box +\end{itemize} + +\section{Sub address} + + When sending a message to a landline, you simply send to the landline + number. In the UK, all of the mobile operators (bar one) understand + sending messages to landlines and pass the messages to the BTText + system for delivery to the landline. + + The specification for landline SMS allows for the possibility of more + than one device on a single landline. These can be configured with Sub + addresses which are a single digit. To send a message to a specific + device the message is sent to the landline number with an extra digit + appended to the end. The telco can define a default sub address (9 in + the UK) which is used when the extra digit is not appended to the end. + When the call comes in, part of the calling line ID is the sub + address, so that only one device on the line answers the call and + receives the message. + + Sub addresses also work for outgoing messages. Part of the number + called by the device to send a message is its sub address. Sending + from the default sub address (9 in the UK) means the message is + delivered with the sender being the normal landline number. Sending + from any other sub address makes the sender the landline number with + an extra digit on the end. + + Using Asterisk, you can make use of the sub addresses for sending and + receiving messages. Using DDI (DID, i.e. multiple numbers on the line + on ISDN) you can also make use of many different numbers for SMS. + +\section{extensions.conf} + + The following contexts are recommended. +\begin{verbatim} +; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive +s, with the queue (called number and sub address) in ${EXTEN} +; Running an app after receipt of the text allows the app to find all messages +in the queue and handle them, e.g. email them. +; The app may be something like smsq --process=somecommand --queue=${EXTEN} +to run a command for each received message +; See below for usage +[smsmtrx] +exten = _X.,1, SMS(${EXTEN}|a) +exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}") +exten = _X.,3,Hangup +; Mobile originated, RX. This is receiving a message from a device, e.g. a Magi +c Messenger on a sip extension +; Running an app after receipt of the text allows the app to find all messages +in the queue and handle then, e.g. sending them to the public SMSC +; The app may be something like smsq --process=somecommand --queue=${EXTEN} +to run a command for each received message +; See below for example usage +[smsmorx] +exten = _X.,1, SMS(${EXTEN}|sa) +exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}") +exten = _X.,3,Hangup + + smsmtrx is normally accessed by an incoming call from the SMSC. In the + UK this call is from a CLI of 080058752X0 where X is the sub address. + As such a typical usage in the extensions.conf at the point of + handling an incoming call is:- +exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1) +exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:8:1},1) + + Alternatively, if you have the correct national prefix on incoming + CLI, e.g. using zaphfc, you might use:- +exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1) +exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1) + + smsmorx is normally accessed by a call from a local sip device + connected to a Magic Messenger. It could however by that you are + operating Asterisk as a message centre for calls from outside. Either + way, you look at the called number and goto smsmorx. In the UK, the + SMSC number that would be dialed is 1709400X where X is the caller sub + address. As such typical usage in extension.config at the point of + handling a call from a sip phone is:- +exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1) +exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) +\end{verbatim} + +\section{Using smsq} + + smsq is a simple helper application designed to make it easy to send + messages from a command line. it is intended to run on the Asterisk + box and have direct access to the queue directories for SMS and for + Asterisk. + + In its simplest form you can send an SMS by a command such as + smsq 0123456789 This is a test to 0123456789 + This would create a queue file for a mobile originated TX message in + queue 0 to send the text "This is a test to 0123456789" to 0123456789. + It would then place a file in the /var/spool/asterisk/outgoing + directory to initiate a call to 17094009 (the default message centre + in smsq) attached to application SMS with argument of the queue name + (0). + + Normally smsq will queue a message ready to send, and will then create + a file in the Asterisk outgoing directory causing Asterisk to actually + connect to the message centre or device and actually send the pending + message(s). + + Using --process, smsq can however be used on received queues to run a + command for each file (matching the queue if specified) with various + environment variables set based on the message (see below); + smsq options:- +\begin{verbatim} + --help + Show help text + --usage + Show usage + --queue + -q + Specify a specific queue + In no specified, messages are queued under queue "0" + --da + -d + Specify destination address + --oa + -o + Specify originating address + This also implies that we are generating a mobile terminated message + --ud + -m + Specify the actual message + --ud-file + -f + Specify a file to be read for the context of the message + A blank filename (e.g. --ud-file= on its own) means read stdin. Very + useful when using via ssh where command line parsing could mess up the + message. + --mt + -t + Mobile terminated message to be generated + --mo + Mobile originated message to be generated + Default + --tx + Transmit message + Default + --rx + -r + Generate a message in the receive queue + --UTF-8 + Treat the file as UTF-8 encoded (default) + --UCS-1 + Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded + --UCS-2 + Treat the file as raw 16 bit bigendian USC-2 data + --process + Specific a command to process for each file in the queue + Implies --rx and --mt if not otherwise specified. + Sets environment variables for every possible variable, and also ud, + ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files. + --motx-channel + Specify the channel for motx calls + May contain X to use sub address based on queue name or may be full + number + Default is Local/1709400X + --motx-callerid + Specify the caller ID for motx calls + The default is the queue name without -X suffix + --motx-wait + Wait time for motx call + Default 10 + --motx-delay + Retry time for motx call + Default 1 + --motx-retries + Retries for motx call + Default 10 + --mttx-channel + Specify the channel for mttx calls + Default is Local/ and the queue name without -X suffix + --mtttx-callerid + Specify the callerid for mttx calls + May include X to use sub address based on queue name or may be full + number + Default is 080058752X0 + --mttx-wait + Wait time for mttx call + Default 10 + --mttx-delay + Retry time for mttx call + Default 30 + --mttx-retries + Retries for mttx call + Default 100 + --default-sub-address + The default sub address assumed (e.g. for X in CLI and dialled numbers + as above) when none added (-X) to queue + Default 9 + --no-dial + -x + Create queue, but do not dial to send message + --no-wait + Do not wait if a call appears to be in progress + This could have a small window where a message is queued but not + sent, so regular calls to smsq should be done to pick up any missed + messages + --concurrent + How many concurrent calls to allow (per queue), default 1 + --mr + -n + Message reference + --pid + -p + Protocol ID + --dcs + Data coding scheme + --udh + Specific hex string of user data header specified (not including the + initial length byte) + May be a blank string to indicate header is included in the user data + already but user data header indication to be set. + --srr + Status report requested + --rp + Return path requested + --vp + Specify validity period (seconds) + --scts + Specify timestamp (YYYY-MM-DDTHH:MM:SS) + --spool-dir + Spool dir (in which sms and outgoing are found) + Default /var/spool/asterisk + + Other arguments starting '-' or '--' are invalid and will cause an + error. Any trailing arguments are processed as follows:- + * If the message is mobile originating and no destination address + has been specified, then the first argument is assumed to be a + destination address + * If the message is mobile terminating and no destination address + has been specified, then the first argument is assumed to be the + queue name + * If there is no user data, or user data file specified, then any + following arguments are assumed to be the message, which are + concatenated. + * If no user data is specified, then no message is sent. However, + unless --no-dial is specified, smsq checks for pending messages + and generates an outgoing anyway +\end{verbatim} + + Note that when smsq attempts to make a file in + /var/spool/asterisk/outgoing, it checks if there is already a call + queued for that queue. It will try several filenames, up to the + --concurrent setting. If these files exist, then this means Asterisk + is already queued to send all messages for that queue, and so Asterisk + should pick up the message just queued. However, this alone could + create a race condition, so if the files exist then smsq will wait up + to 3 seconds to confirm it still exists or if the queued messages have + been sent already. The --no-wait turns off this behaviour. Basically, + this means that if you have a lot of messages to send all at once, + Asterisk will not make unlimited concurrent calls to the same message + centre or device for the same queue. This is because it is generally + more efficient to make one call and send all of the messages one after + the other. + + smsq can be used with no arguments, or with a queue name only, and it + will check for any pending messages and cause an outgoing if there are + any. It only sets up one outgoing call at a time based on the first + queued message it finds. A outgoing call will normally send all queued + messages for that queue. One way to use smsq would be to run with no + queue name (so any queue) every minute or every few seconds to send + pending message. This is not normally necessary unless --no-dial is + selected. Note that smsq does only check motx or mttx depending on the + options selected, so it would need to be called twice as a general + check. + + UTF-8 is used to parse command line arguments for user data, and is + the default when reading a file. If an invalid UTF-8 sequence is + found, it is treated as UCS-1 data (i.e, as is). + The --process option causes smsq to scan the specified queue (default + is mtrx) for messages (matching the queue specified, or any if queue + not specified) and run a command and delete the file. The command is + run with a number of environment variables set as follows. Note that + these are unset if not needed and not just taken from the calling + environment. This allows simple processing of incoming messages +\begin{verbatim} + $queue + Set if a queue specified + $?srr + srr is set (to blank) if srr defined and has value 1. + $?rp + rp is set (to blank) if rp defined and has value 1. + $ud + User data, UTF-8 encoding, including any control characters, but with + nulls stripped out + Useful for the content of emails, for example, as it includes any + newlines, etc. + $ude + User data, escaped UTF-8, including all characters, but control + characters \n, \r, \t, \f, \xxx and \ is escaped as \\ + Useful guaranteed one line printable text, so useful in Subject lines + of emails, etc + $ud8 + Hex UCS-1 coding of user data (2 hex digits per character) + Present only if all user data is in range U+0000 to U+00FF + $ud16 + Hex UCS-2 coding of user data (4 hex digits per character) + other + Other fields set using their field name, e.g. mr, pid, dcs, etc. udh + is a hex byte string +\end{verbatim} + +\section{File formats} + + By default all queues are held in a director /var/spool/asterisk/sms. + Within this directory are sub directories mtrx, mttx, morx, motx which + hold the received messages and the messages ready to send. Also, + /var/log/asterisk/sms is a log file of all messages handled. + + The file name in each queue directory starts with the queue parameter + to SMS which is normally the CLI used for an outgoing message or the + called number on an incoming message, and may have -X (X being sub + address) appended. If no queue ID is known, then 0 is used by smsq by + default. After this is a dot, and then any text. Files are scanned for + matching queue ID and a dot at the start. This means temporary files + being created can be given a different name not starting with a queue + (we recommend a . on the start of the file name for temp files). + Files in these queues are in the form of a simple text file where each + line starts with a keyword and an = and then data. udh and ud have + options for hex encoding, see below. + + UTF-8. The user data (ud) field is treated as being UTF-8 encoded + unless the DCS is specified indicating 8 bit format. If 8 bit format + is specified then the user data is sent as is. + The keywords are as follows:- +\begin{verbatim} + oa Originating address + The phone number from which the message came + Present on mobile terminated messages and is the CLI for morx messages + da + Destination Address + The phone number to which the message is sent + Present on mobile originated messages + scts + The service centre time stamp + Format YYYY-MM-DDTHH:MM:SS + Present on mobile terminated messages + pid + One byte decimal protocol ID + See GSM specs for more details + Normally 0 or absent + dcs + One byte decimal data coding scheme + If omitted, a sensible default is used (see below) + See GSM specs for more details + mr + One byte decimal message reference + Present on mobile originated messages, added by default if absent + srr + 0 or 1 for status report request + Does not work in UK yet, not implemented in app\_sms yet + rp + 0 or 1 return path + See GSM specs for details + vp + Validity period in seconds + Does not work in UK yet + udh + Hex string of user data header prepended to the SMS contents, + excluding initial length byte. + Consistent with ud, this is specified as udh# rather than udh= + If blank, this means that the udhi flag will be set but any user data + header must be in the ud field + ud + User data, may be text, or hex, see below +\end{verbatim} + + udh is specified as as udh\# followed by hex (2 hex digits per byte). + If present, then the user data header indicator bit is set, and the + length plus the user data header is added to the start of the user + data, with padding if necessary (to septet boundary in 7 bit format). + User data can hold an USC character codes U+0000 to U+FFFF. Any other + characters are coded as U+FEFF + + ud can be specified as ud= followed by UTF-8 encoded text if it + contains no control characters, i.e. only (U+0020 to U+FFFF). Any + invalid UTF-8 sequences are treated as is (U+0080-U+00FF). + + ud can also be specified as ud\# followed by hex (2 hex digits per + byte) containing characters U+0000 to U+00FF only. + + ud can also be specified as ud\#\# followed by hex (4 hex digits per + byte) containing UCS-2 characters. + + When written by app\_sms (e.g. incoming messages), the file is written + with ud= if it can be (no control characters). If it cannot, the a + comment line ;ud= is used to show the user data for human readability + and ud\# or ud\#\# is used. + +\section{Delivery reports} + + The SMS specification allows for delivery reports. These are requested + using the srr bit. However, as these do not work in the UK yet they + are not fully implemented in this application. If anyone has a telco + that does implement these, please let me know. BT in the UK have a non + standard way to do this by starting the message with *0\#, and so this + application may have a UK specific bodge in the near future to handle + these. +\begin{verbatim} + The main changes that are proposed for delivery report handling are :- + * New queues for sent messages, one file for each destination + address and message reference. + * New field in message format, user reference, allowing applications + to tie up their original message with a report. + * Handling of the delivery confirmation/rejection and connecting to + the outgoing message - the received message file would then have + fields for the original outgoing message and user reference + allowing applications to handle confirmations better. +\end{verbatim} diff --git a/doc/tex/ast_agi_commands.tex b/doc/tex/ast_agi_commands.tex new file mode 100644 index 000000000..5a63d3a3e --- /dev/null +++ b/doc/tex/ast_agi_commands.tex @@ -0,0 +1,582 @@ +% This file is automatically generated by the "manager dump actiondocs" CLI command. Any manual edits will be lost. +\section{answer} +\subsection{Summary} +\begin{verbatim} +Answer channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: ANSWER + Answers channel if not already in answer state. Returns -1 on + channel failure, or 0 if successful. + +\end{verbatim} + + +\section{channel status} +\subsection{Summary} +\begin{verbatim} +Returns status of the connected channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: CHANNEL STATUS [<channelname>] + Returns the status of the specified channel. + If no channel name is given the returns the status of the + current channel. Return values: + 0 Channel is down and available + 1 Channel is down, but reserved + 2 Channel is off hook + 3 Digits (or equivalent) have been dialed + 4 Line is ringing + 5 Remote end is ringing + 6 Line is up + 7 Line is busy + +\end{verbatim} + + +\section{database del} +\subsection{Summary} +\begin{verbatim} +Removes database key/value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: DATABASE DEL <family> <key> + Deletes an entry in the Asterisk database for a + given family and key. + Returns 1 if successful, 0 otherwise. + +\end{verbatim} + + +\section{database deltree} +\subsection{Summary} +\begin{verbatim} +Removes database keytree/value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: DATABASE DELTREE <family> [keytree] + Deletes a family or specific keytree within a family + in the Asterisk database. + Returns 1 if successful, 0 otherwise. + +\end{verbatim} + + +\section{database get} +\subsection{Summary} +\begin{verbatim} +Gets database value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: DATABASE GET <family> <key> + Retrieves an entry in the Asterisk database for a + given family and key. + Returns 0 if <key> is not set. Returns 1 if <key> + is set and returns the variable in parentheses. + Example return code: 200 result=1 (testvariable) + +\end{verbatim} + + +\section{database put} +\subsection{Summary} +\begin{verbatim} +Adds/updates database value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: DATABASE PUT <family> <key> <value> + Adds or updates an entry in the Asterisk database for a + given family, key, and value. + Returns 1 if successful, 0 otherwise. + +\end{verbatim} + + +\section{exec} +\subsection{Summary} +\begin{verbatim} +Executes a given Application +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: EXEC <application> <options> + Executes <application> with given <options>. + Returns whatever the application returns, or -2 on failure to find application + +\end{verbatim} + + +\section{get data} +\subsection{Summary} +\begin{verbatim} +Prompts for DTMF on a channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: GET DATA <file to be streamed> [timeout] [max digits] + Stream the given file, and recieve DTMF data. Returns the digits received +from the channel at the other end. + +\end{verbatim} + + +\section{get full variable} +\subsection{Summary} +\begin{verbatim} +Evaluates a channel expression +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: GET FULL VARIABLE <variablename> [<channel name>] + Returns 0 if <variablename> is not set or channel does not exist. Returns 1 +if <variablename> is set and returns the variable in parenthesis. Understands +complex variable names and builtin variables, unlike GET VARIABLE. + example return code: 200 result=1 (testvariable) + +\end{verbatim} + + +\section{get option} +\subsection{Summary} +\begin{verbatim} +Stream file, prompt for DTMF, with timeout +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: GET OPTION <filename> <escape_digits> [timeout] + Behaves similar to STREAM FILE but used with a timeout option. + +\end{verbatim} + + +\section{get variable} +\subsection{Summary} +\begin{verbatim} +Gets a channel variable +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: GET VARIABLE <variablename> + Returns 0 if <variablename> is not set. Returns 1 if <variablename> + is set and returns the variable in parentheses. + example return code: 200 result=1 (testvariable) + +\end{verbatim} + + +\section{hangup} +\subsection{Summary} +\begin{verbatim} +Hangup the current channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: HANGUP [<channelname>] + Hangs up the specified channel. + If no channel name is given, hangs up the current channel + +\end{verbatim} + + +\section{noop} +\subsection{Summary} +\begin{verbatim} +Does nothing +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: NoOp + Does nothing. + +\end{verbatim} + + +\section{receive char} +\subsection{Summary} +\begin{verbatim} +Receives one character from channels supporting it +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: RECEIVE CHAR <timeout> + Receives a character of text on a channel. Specify timeout to be the + maximum time to wait for input in milliseconds, or 0 for infinite. Most channels + do not support the reception of text. Returns the decimal value of the character + if one is received, or 0 if the channel does not support text reception. Returns + -1 only on error/hangup. + +\end{verbatim} + + +\section{receive text} +\subsection{Summary} +\begin{verbatim} +Receives text from channels supporting it +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: RECEIVE TEXT <timeout> + Receives a string of text on a channel. Specify timeout to be the + maximum time to wait for input in milliseconds, or 0 for infinite. Most channels + do not support the reception of text. Returns -1 for failure or 1 for success, and the string in parentheses. + +\end{verbatim} + + +\section{record file} +\subsection{Summary} +\begin{verbatim} +Records to a given file +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: RECORD FILE <filename> <format> <escape digits> <timeout> \ + [offset samples] [BEEP] [s=silence] + Record to a file until a given dtmf digit in the sequence is received + Returns -1 on hangup or error. The format will specify what kind of file + will be recorded. The timeout is the maximum record time in milliseconds, or + -1 for no timeout. "Offset samples" is optional, and, if provided, will seek + to the offset without exceeding the end of the file. "silence" is the number + of seconds of silence allowed before the function returns despite the + lack of dtmf digits or reaching timeout. Silence value must be + preceeded by "s=" and is also optional. + +\end{verbatim} + + +\section{say alpha} +\subsection{Summary} +\begin{verbatim} +Says a given character string +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY ALPHA <number> <escape digits> + Say a given character string, returning early if any of the given DTMF digits + are received on the channel. Returns 0 if playback completes without a digit + being pressed, or the ASCII numerical value of the digit if one was pressed or + -1 on error/hangup. + +\end{verbatim} + + +\section{say digits} +\subsection{Summary} +\begin{verbatim} +Says a given digit string +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY DIGITS <number> <escape digits> + Say a given digit string, returning early if any of the given DTMF digits + are received on the channel. Returns 0 if playback completes without a digit + being pressed, or the ASCII numerical value of the digit if one was pressed or + -1 on error/hangup. + +\end{verbatim} + + +\section{say number} +\subsection{Summary} +\begin{verbatim} +Says a given number +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY NUMBER <number> <escape digits> [gender] + Say a given number, returning early if any of the given DTMF digits + are received on the channel. Returns 0 if playback completes without a digit + being pressed, or the ASCII numerical value of the digit if one was pressed or + -1 on error/hangup. + +\end{verbatim} + + +\section{say phonetic} +\subsection{Summary} +\begin{verbatim} +Says a given character string with phonetics +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY PHONETIC <string> <escape digits> + Say a given character string with phonetics, returning early if any of the + given DTMF digits are received on the channel. Returns 0 if playback + completes without a digit pressed, the ASCII numerical value of the digit + if one was pressed, or -1 on error/hangup. + +\end{verbatim} + + +\section{say date} +\subsection{Summary} +\begin{verbatim} +Says a given date +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY DATE <date> <escape digits> + Say a given date, returning early if any of the given DTMF digits are + received on the channel. <date> is number of seconds elapsed since 00:00:00 + on January 1, 1970, Coordinated Universal Time (UTC). Returns 0 if playback + completes without a digit being pressed, or the ASCII numerical value of the + digit if one was pressed or -1 on error/hangup. + +\end{verbatim} + + +\section{say time} +\subsection{Summary} +\begin{verbatim} +Says a given time +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY TIME <time> <escape digits> + Say a given time, returning early if any of the given DTMF digits are + received on the channel. <time> is number of seconds elapsed since 00:00:00 + on January 1, 1970, Coordinated Universal Time (UTC). Returns 0 if playback + completes without a digit being pressed, or the ASCII numerical value of the + digit if one was pressed or -1 on error/hangup. + +\end{verbatim} + + +\section{say datetime} +\subsection{Summary} +\begin{verbatim} +Says a given time as specfied by the format given +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SAY DATETIME <time> <escape digits> [format] [timezone] + Say a given time, returning early if any of the given DTMF digits are + received on the channel. <time> is number of seconds elapsed since 00:00:00 + on January 1, 1970, Coordinated Universal Time (UTC). [format] is the format + the time should be said in. See voicemail.conf (defaults to "ABdY + 'digits/at' IMp"). Acceptable values for [timezone] can be found in + /usr/share/zoneinfo. Defaults to machine default. Returns 0 if playback + completes without a digit being pressed, or the ASCII numerical value of the + digit if one was pressed or -1 on error/hangup. + +\end{verbatim} + + +\section{send image} +\subsection{Summary} +\begin{verbatim} +Sends images to channels supporting it +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SEND IMAGE <image> + Sends the given image on a channel. Most channels do not support the + transmission of images. Returns 0 if image is sent, or if the channel does not + support image transmission. Returns -1 only on error/hangup. Image names + should not include extensions. + +\end{verbatim} + + +\section{send text} +\subsection{Summary} +\begin{verbatim} +Sends text to channels supporting it +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SEND TEXT "<text to send>" + Sends the given text on a channel. Most channels do not support the + transmission of text. Returns 0 if text is sent, or if the channel does not + support text transmission. Returns -1 only on error/hangup. Text + consisting of greater than one word should be placed in quotes since the + command only accepts a single argument. + +\end{verbatim} + + +\section{set autohangup} +\subsection{Summary} +\begin{verbatim} +Autohangup channel in some time +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET AUTOHANGUP <time> + Cause the channel to automatically hangup at <time> seconds in the + future. Of course it can be hungup before then as well. Setting to 0 will + cause the autohangup feature to be disabled on this channel. + +\end{verbatim} + + +\section{set callerid} +\subsection{Summary} +\begin{verbatim} +Sets callerid for the current channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET CALLERID <number> + Changes the callerid of the current channel. + +\end{verbatim} + + +\section{set context} +\subsection{Summary} +\begin{verbatim} +Sets channel context +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET CONTEXT <desired context> + Sets the context for continuation upon exiting the application. + +\end{verbatim} + + +\section{set extension} +\subsection{Summary} +\begin{verbatim} +Changes channel extension +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET EXTENSION <new extension> + Changes the extension for continuation upon exiting the application. + +\end{verbatim} + + +\section{set music} +\subsection{Summary} +\begin{verbatim} +Enable/Disable Music on hold generator +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET MUSIC ON <on|off> <class> + Enables/Disables the music on hold generator. If <class> is + not specified, then the default music on hold class will be used. + Always returns 0. + +\end{verbatim} + + +\section{set priority} +\subsection{Summary} +\begin{verbatim} +Set channel dialplan priority +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET PRIORITY <priority> + Changes the priority for continuation upon exiting the application. + The priority must be a valid priority or label. + +\end{verbatim} + + +\section{set variable} +\subsection{Summary} +\begin{verbatim} +Sets a channel variable +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: SET VARIABLE <variablename> <value> + +\end{verbatim} + + +\section{stream file} +\subsection{Summary} +\begin{verbatim} +Sends audio file on channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: STREAM FILE <filename> <escape digits> [sample offset] + Send the given file, allowing playback to be interrupted by the given + digits, if any. Use double quotes for the digits if you wish none to be + permitted. If sample offset is provided then the audio will seek to sample + offset before play starts. Returns 0 if playback completes without a digit + being pressed, or the ASCII numerical value of the digit if one was pressed, + or -1 on error or if the channel was disconnected. Remember, the file + extension must not be included in the filename. + +\end{verbatim} + + +\section{control stream file} +\subsection{Summary} +\begin{verbatim} +Sends audio file on channel and allows the listner to control the stream +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: CONTROL STREAM FILE <filename> <escape digits> [skipms] [ffchar] [rewchr] [pausechr] + Send the given file, allowing playback to be controled by the given + digits, if any. Use double quotes for the digits if you wish none to be + permitted. Returns 0 if playback completes without a digit + being pressed, or the ASCII numerical value of the digit if one was pressed, + or -1 on error or if the channel was disconnected. Remember, the file + extension must not be included in the filename. + + Note: ffchar and rewchar default to * and # respectively. + +\end{verbatim} + + +\section{tdd mode} +\subsection{Summary} +\begin{verbatim} +Toggles TDD mode (for the deaf) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: TDD MODE <on|off> + Enable/Disable TDD transmission/reception on a channel. Returns 1 if + successful, or 0 if channel is not TDD-capable. + +\end{verbatim} + + +\section{verbose} +\subsection{Summary} +\begin{verbatim} +Logs a message to the asterisk verbose log +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: VERBOSE <message> <level> + Sends <message> to the console via verbose message system. + <level> is the the verbose level (1-4) + Always returns 1. + +\end{verbatim} + + +\section{wait for digit} +\subsection{Summary} +\begin{verbatim} +Waits for a digit to be pressed +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: WAIT FOR DIGIT <timeout> + Waits up to 'timeout' milliseconds for channel to receive a DTMF digit. + Returns -1 on channel failure, 0 if no digit is received in the timeout, or + the numerical value of the ascii of the digit if one is received. Use -1 + for the timeout value if you desire the call to block indefinitely. + +\end{verbatim} + + diff --git a/doc/tex/ast_appdocs.tex b/doc/tex/ast_appdocs.tex new file mode 100644 index 000000000..d4f36d4ce --- /dev/null +++ b/doc/tex/ast_appdocs.tex @@ -0,0 +1,3276 @@ +% This file is automatically generated by the "core dump appdocs" CLI command. Any manual edits will be lost. +\section{AddQueueMember} +\subsection{Synopsis} +\begin{verbatim} +Dynamically adds queue members +\end{verbatim} +\subsection{Description} +\begin{verbatim} + AddQueueMember(queuename[|interface[|penalty[|options[|membername]]]]): +Dynamically adds interface to an existing queue. +If the interface is already in the queue it will return an error. + This application sets the following channel variable upon completion: + AQMSTATUS The status of the attempt to add a queue member as a + text string, one of + ADDED | MEMBERALREADY | NOSUCHQUEUE +Example: AddQueueMember(techsupport|SIP/3000) + +\end{verbatim} + + +\section{ADSIProg} +\subsection{Synopsis} +\begin{verbatim} +Load Asterisk ADSI Scripts into phone +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ADSIProg(script): This application programs an ADSI Phone with the given +script. If nothing is specified, the default script (asterisk.adsi) is used. + +\end{verbatim} + + +\section{AgentLogin} +\subsection{Synopsis} +\begin{verbatim} +Call agent login +\end{verbatim} +\subsection{Description} +\begin{verbatim} + AgentLogin([AgentNo][|options]): +Asks the agent to login to the system. Always returns -1. While +logged in, the agent can receive calls and will hear a 'beep' +when a new call comes in. The agent can dump the call by pressing +the star key. +The option string may contain zero or more of the following characters: + 's' -- silent login - do not announce the login ok segment after agent logged in/off + +\end{verbatim} + + +\section{AgentMonitorOutgoing} +\subsection{Synopsis} +\begin{verbatim} +Record agent's outgoing call +\end{verbatim} +\subsection{Description} +\begin{verbatim} + AgentMonitorOutgoing([options]): +Tries to figure out the id of the agent who is placing outgoing call based on +comparison of the callerid of the current interface and the global variable +placed by the AgentCallbackLogin application. That's why it should be used only +with the AgentCallbackLogin app. Uses the monitoring functions in chan_agent +instead of Monitor application. That have to be configured in the agents.conf file. + +Return value: +Normally the app returns 0 unless the options are passed. + +Options: + 'd' - make the app return -1 if there is an error condition 'c' - change the CDR so that the source of the call is 'Agent/agent_id' + 'n' - don't generate the warnings when there is no callerid or the + agentid is not known. + It's handy if you want to have one context for agent and non-agent calls. + +\end{verbatim} + + +\section{AGI} +\subsection{Synopsis} +\begin{verbatim} +Executes an AGI compliant application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant +program on a channel. AGI allows Asterisk to launch external programs +written in any language to control a telephony channel, play audio, +read DTMF digits, etc. by communicating with the AGI protocol on stdin +and stdout. + This channel will stop dialplan execution on hangup inside of this +application, except when using DeadAGI. Otherwise, dialplan execution +will continue normally. + A locally executed AGI script will receive SIGHUP on hangup from the channel +except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel +variable to "no" before executing the AGI application. + Using 'EAGI' provides enhanced AGI, with incoming audio available out of band +on file descriptor 3 + + Use the CLI command 'agi show' to list available agi commands + This application sets the following channel variable upon completion: + AGISTATUS The status of the attempt to the run the AGI script + text string, one of SUCCESS | FAILED | NOTFOUND | HANGUP + +\end{verbatim} + + +\section{AlarmReceiver} +\subsection{Synopsis} +\begin{verbatim} +Provide support for receiving alarm reports from a burglar or fire alarm panel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco +Contact ID. This application should be called whenever there is an alarm +panel calling in to dump its events. The application will handshake with the +alarm panel, and receive events, validate them, handshake them, and store them +until the panel hangs up. Once the panel hangs up, the application will run the +system command specified by the eventcmd setting in alarmreceiver.conf and pipe +the events to the standard input of the application. The configuration file also +contains settings for DTMF timing, and for the loudness of the acknowledgement +tones. + +\end{verbatim} + + +\section{AMD} +\subsection{Synopsis} +\begin{verbatim} +Attempts to detect answering machines +\end{verbatim} +\subsection{Description} +\begin{verbatim} + AMD([initialSilence][|greeting][|afterGreetingSilence][|totalAnalysisTime] + [|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords] + [|silenceThreshold]) + This application attempts to detect answering machines at the beginning + of outbound calls. Simply call this application after the call + has been answered (outbound only, of course). + When loaded, AMD reads amd.conf and uses the parameters specified as + default values. Those default values get overwritten when calling AMD + with parameters. +- 'initialSilence' is the maximum silence duration before the greeting. If + exceeded then MACHINE. +- 'greeting' is the maximum length of a greeting. If exceeded then MACHINE. +- 'afterGreetingSilence' is the silence after detecting a greeting. + If exceeded then HUMAN. +- 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide + on a HUMAN or MACHINE. +- 'minimumWordLength'is the minimum duration of Voice to considered as a word. +- 'betweenWordsSilence' is the minimum duration of silence after a word to + consider the audio that follows as a new word. +- 'maximumNumberOfWords'is the maximum number of words in the greeting. + If exceeded then MACHINE. +- 'silenceThreshold' is the silence threshold. +This application sets the following channel variable upon completion: + AMDSTATUS - This is the status of the answering machine detection. + Possible values are: + MACHINE | HUMAN | NOTSURE | HANGUP + AMDCAUSE - Indicates the cause that led to the conclusion. + Possible values are: + TOOLONG-<%d total_time> + INITIALSILENCE-<%d silenceDuration>-<%d initialSilence> + HUMAN-<%d silenceDuration>-<%d afterGreetingSilence> + MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords> + LONGGREETING-<%d voiceDuration>-<%d greeting> + +\end{verbatim} + + +\section{Answer} +\subsection{Synopsis} +\begin{verbatim} +Answer a channel if ringing +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Answer([delay]): If the call has not been answered, this application will +answer it. Otherwise, it has no effect on the call. If a delay is specified, +Asterisk will wait this number of milliseconds before returning to +the dialplan after answering the call. + +\end{verbatim} + + +\section{Authenticate} +\subsection{Synopsis} +\begin{verbatim} +Authenticate a user +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Authenticate(password[|options[|maxdigits]]): This application asks the caller +to enter a given password in order to continue dialplan execution. If the password +begins with the '/' character, it is interpreted as a file which contains a list of +valid passwords, listed 1 password per line in the file. + When using a database key, the value associated with the key can be anything. +Users have three attempts to authenticate before the channel is hung up. + Options: + a - Set the channels' account code to the password that is entered + d - Interpret the given path as database key, not a literal file + m - Interpret the given path as a file which contains a list of account + codes and password hashes delimited with ':', listed one per line in + the file. When one of the passwords is matched, the channel will have + its account code set to the corresponding account code in the file. + r - Remove the database key upon successful entry (valid with 'd' only) + maxdigits - maximum acceptable number of digits. Stops reading after + maxdigits have been entered (without requiring the user to + press the '#' key). + Defaults to 0 - no limit - wait for the user press the '#' key. + +\end{verbatim} + + +\section{BackGround} +\subsection{Synopsis} +\begin{verbatim} +Play an audio file while waiting for digits of an extension to go to. +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Background(filename1[&filename2...][|options[|langoverride][|context]]): +This application will play the given list of files while waiting for an +extension to be dialed by the calling channel. To continue waiting for digits +after this application has finished playing files, the WaitExten application +should be used. The 'langoverride' option explicitly specifies which language +to attempt to use for the requested sound files. If a 'context' is specified, +this is the dialplan context that this application will use when exiting to a +dialed extension. If one of the requested sound files does not exist, call processing will be +terminated. + Options: + s - Causes the playback of the message to be skipped + if the channel is not in the 'up' state (i.e. it + hasn't been answered yet). If this happens, the + application will return immediately. + n - Don't answer the channel before playing the files. + m - Only break if a digit hit matches a one digit + extension in the destination context. +This application sets the following channel variable upon completion: + BACKGROUNDSTATUS The status of the background attempt as a text string, one of + SUCCESS | FAILED + +\end{verbatim} + + +\section{BackgroundDetect} +\subsection{Synopsis} +\begin{verbatim} +Background a file with talk detect +\end{verbatim} +\subsection{Description} +\begin{verbatim} + BackgroundDetect(filename[|sil[|min|[max]]]): Plays back a given +filename, waiting for interruption from a given digit (the digit must +start the beginning of a valid extension, or it will be ignored). +During the playback of the file, audio is monitored in the receive +direction, and if a period of non-silence which is greater than 'min' ms +yet less than 'max' ms is followed by silence for at least 'sil' ms then +the audio playback is aborted and processing jumps to the 'talk' extension +if available. If unspecified, sil, min, and max default to 1000, 100, and +infinity respectively. + +\end{verbatim} + + +\section{Bridge} +\subsection{Synopsis} +\begin{verbatim} +Bridge two channels +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: Bridge(channel[|options]) + Allows the ability to bridge two channels via the dialplan. +The current channel is bridged to the specified 'channel'. +The following options are supported: + p - Play a courtesy tone to 'channel'. +BRIDGERESULT dial plan variable will contain SUCCESS, FAILURE, LOOP, NONEXISTENT or INCOMPATIBLE. + +\end{verbatim} + + +\section{Busy} +\subsection{Synopsis} +\begin{verbatim} +Indicate the Busy condition +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Busy([timeout]): This application will indicate the busy condition to +the calling channel. If the optional timeout is specified, the calling channel +will be hung up after the specified number of seconds. Otherwise, this +application will wait until the calling channel hangs up. + +\end{verbatim} + + +\section{ChangeMonitor} +\subsection{Synopsis} +\begin{verbatim} +Change monitoring filename of a channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ChangeMonitor(filename_base) +Changes monitoring filename of a channel. Has no effect if the channel is not monitored +The argument is the new filename base to use for monitoring this channel. + +\end{verbatim} + + +\section{ChanIsAvail} +\subsection{Synopsis} +\begin{verbatim} +Check channel availability +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ChanIsAvail(Technology/resource[&Technology2/resource2...][|options]): +This application will check to see if any of the specified channels are +available. The following variables will be set by this application: + ${AVAILCHAN} - the name of the available channel, if one exists + ${AVAILORIGCHAN} - the canonical channel name that was used to create the channel + ${AVAILSTATUS} - the status code for the available channel + Options: + s - Consider the channel unavailable if the channel is in use at all + t - Simply checks if specified channels exist in the channel list + (implies option s) + +\end{verbatim} + + +\section{ChannelRedirect} +\subsection{Synopsis} +\begin{verbatim} +Redirects given channel to a dialplan target. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ChannelRedirect(channel|[[context|]extension|]priority): + Sends the specified channel to the specified extension priority + +\end{verbatim} + + +\section{ChanSpy} +\subsection{Synopsis} +\begin{verbatim} +Listen to a channel, and optionally whisper into it +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ChanSpy([chanprefix][|options]): This application is used to listen to the +audio from an Asterisk channel. This includes the audio coming in and +out of the channel being spied on. If the 'chanprefix' parameter is specified, +only channels beginning with this string will be spied upon. + While spying, the following actions may be performed: + - Dialing # cycles the volume level. + - Dialing * will stop spying and look for another channel to spy on. + - Dialing a series of digits followed by # builds a channel name to append + to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing + the digits '1234#' while spying will begin spying on the channel + 'Agent/1234'. + Note: The X option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will + exit to it. This also disables choosing a channel based on 'chanprefix' + and a digit sequence. + Options: + b - Only spy on channels involved in a bridged call. + g(grp) - Match only channels where their ${SPYGROUP} variable is set to + contain 'grp' in an optional : delimited list. + q - Don't play a beep when beginning to spy on a channel, or speak the + selected channel name. + r[(basename)] - Record the session to the monitor spool directory. An + optional base for the filename may be specified. The + default is 'chanspy'. + v([value]) - Adjust the initial volume in the range from -4 to 4. A + negative value refers to a quieter setting. + w - Enable 'whisper' mode, so the spying channel can talk to + the spied-on channel. + W - Enable 'private whisper' mode, so the spying channel can + talk to the spied-on channel but cannot listen to that + channel. + o - Only listen to audio coming from this channel. + X - Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the SPY_EXIT_CONTEXT channel variable. The + name of the last channel that was spied on will be stored + in the SPY_CHANNEL variable. + +\end{verbatim} + + +\section{ClearHash} +\subsection{Synopsis} +\begin{verbatim} +Clear the keys from a specified hashname +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ClearHash(<hashname>) + Clears all keys out of the specified hashname + +\end{verbatim} + + +\section{Congestion} +\subsection{Synopsis} +\begin{verbatim} +Indicate the Congestion condition +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Congestion([timeout]): This application will indicate the congestion +condition to the calling channel. If the optional timeout is specified, the +calling channel will be hung up after the specified number of seconds. +Otherwise, this application will wait until the calling channel hangs up. + +\end{verbatim} + + +\section{ContinueWhile} +\subsection{Synopsis} +\begin{verbatim} +Restart a While loop +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: ContinueWhile() +Returns to the top of the while loop and re-evaluates the conditional. + +\end{verbatim} + + +\section{ControlPlayback} +\subsection{Synopsis} +\begin{verbatim} +Play a file with fast forward and rewind +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|options]]]]]]]): +This application will play back the given filename. By default, the '*' key +can be used to rewind, and the '#' key can be used to fast-forward. +Parameters: + skipms - This is number of milliseconds to skip when rewinding or + fast-forwarding. + ff - Fast-forward when this DTMF digit is received. + rew - Rewind when this DTMF digit is received. + stop - Stop playback when this DTMF digit is received. + pause - Pause playback when this DTMF digit is received. + restart - Restart playback when this DTMF digit is received. +Options: + o(#) - Start at # ms from the beginning of the file. +This application sets the following channel variables upon completion: + CPLAYBACKSTATUS - This variable contains the status of the attempt as a text + string, one of: SUCCESS | USERSTOPPED | ERROR + CPLAYBACKOFFSET - This contains the offset in ms into the file where + playback was at when it stopped. -1 is end of file. + +\end{verbatim} + + +\section{DateTime} +\subsection{Synopsis} +\begin{verbatim} +Says a specified time in a custom format +\end{verbatim} +\subsection{Description} +\begin{verbatim} +DateTime([unixtime][|[timezone][|format]]) + unixtime: time, in seconds since Jan 1, 1970. May be negative. + defaults to now. + timezone: timezone, see /usr/share/zoneinfo for a list. + defaults to machine default. + format: a format the time is to be said in. See voicemail.conf. + defaults to "ABdY 'digits/at' IMp" + +\end{verbatim} + + +\section{DBdel} +\subsection{Synopsis} +\begin{verbatim} +Delete a key from the database +\end{verbatim} +\subsection{Description} +\begin{verbatim} + DBdel(family/key): This application will delete a key from the Asterisk +database. + This application has been DEPRECATED in favor of the DB_DELETE function. + +\end{verbatim} + + +\section{DBdeltree} +\subsection{Synopsis} +\begin{verbatim} +Delete a family or keytree from the database +\end{verbatim} +\subsection{Description} +\begin{verbatim} + DBdeltree(family[/keytree]): This application will delete a family or keytree +from the Asterisk database + +\end{verbatim} + + +\section{DeadAGI} +\subsection{Synopsis} +\begin{verbatim} +Executes AGI on a hungup channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant +program on a channel. AGI allows Asterisk to launch external programs +written in any language to control a telephony channel, play audio, +read DTMF digits, etc. by communicating with the AGI protocol on stdin +and stdout. + This channel will stop dialplan execution on hangup inside of this +application, except when using DeadAGI. Otherwise, dialplan execution +will continue normally. + A locally executed AGI script will receive SIGHUP on hangup from the channel +except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel +variable to "no" before executing the AGI application. + Using 'EAGI' provides enhanced AGI, with incoming audio available out of band +on file descriptor 3 + + Use the CLI command 'agi show' to list available agi commands + This application sets the following channel variable upon completion: + AGISTATUS The status of the attempt to the run the AGI script + text string, one of SUCCESS | FAILED | NOTFOUND | HANGUP + +\end{verbatim} + + +\section{Dial} +\subsection{Synopsis} +\begin{verbatim} +Place a call and connect to the current channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]): +This application will place calls to one or more specified channels. As soon +as one of the requested channels answers, the originating channel will be +answered, if it has not already been answered. These two channels will then +be active in a bridged call. All other channels that were requested will then +be hung up. + Unless there is a timeout specified, the Dial application will wait +indefinitely until one of the called channels answers, the user hangs up, or +if all of the called channels are busy or unavailable. Dialplan executing will +continue if no requested channels can be called, or if the timeout expires. + + This application sets the following channel variables upon completion: + DIALEDTIME - This is the time from dialing a channel until when it + is disconnected. + ANSWEREDTIME - This is the amount of time for actual call. + DIALSTATUS - This is the status of the call: + CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL + DONTCALL | TORTURE | INVALIDARGS + For the Privacy and Screening Modes, the DIALSTATUS variable will be set to +DONTCALL if the called party chooses to send the calling party to the 'Go Away' +script. The DIALSTATUS variable will be set to TORTURE if the called party +wants to send the caller to the 'torture' script. + This application will report normal termination if the originating channel +hangs up, or if the call is bridged and either of the parties in the bridge +ends the call. + The optional URL will be sent to the called party if the channel supports it. + If the OUTBOUND_GROUP variable is set, all peer channels created by this +application will be put into that group (as in Set(GROUP()=...). + If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this +application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP, +however, the variable will be unset after use. + + Options: + A(x) - Play an announcement to the called party, using 'x' as the file. + C - Reset the CDR for this call. + d - Allow the calling user to dial a 1 digit extension while waiting for + a call to be answered. Exit to that extension if it exists in the + current context, or the context defined in the EXITCONTEXT variable, + if it exists. + D([called][:calling]) - Send the specified DTMF strings *after* the called + party has answered, but before the call gets bridged. The 'called' + DTMF string is sent to the called party, and the 'calling' DTMF + string is sent to the calling party. Both parameters can be used + alone. + f - Force the callerid of the *calling* channel to be set as the + extension associated with the channel using a dialplan 'hint'. + For example, some PSTNs do not allow CallerID to be set to anything + other than the number assigned to the caller. + g - Proceed with dialplan execution at the current extension if the + destination channel hangs up. + G(context^exten^pri) - If the call is answered, transfer the calling party to + the specified priority and the called party to the specified priority+1. + Optionally, an extension, or extension and context may be specified. + Otherwise, the current extension is used. You cannot use any additional + action post answer options in conjunction with this option. + h - Allow the called party to hang up by sending the '*' DTMF digit. + H - Allow the calling party to hang up by hitting the '*' DTMF digit. + i - Asterisk will ignore any forwarding requests it may receive on this + dial attempt. + k - Allow the called party to enable parking of the call by sending + the DTMF sequence defined for call parking in features.conf. + K - Allow the calling party to enable parking of the call by sending + the DTMF sequence defined for call parking in features.conf. + L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are + left. Repeat the warning every 'z' ms. The following special + variables can be used with this option: + * LIMIT_PLAYAUDIO_CALLER yes|no (default yes) + Play sounds to the caller. + * LIMIT_PLAYAUDIO_CALLEE yes|no + Play sounds to the callee. + * LIMIT_TIMEOUT_FILE File to play when time is up. + * LIMIT_CONNECT_FILE File to play when call begins. + * LIMIT_WARNING_FILE File to play as warning if 'y' is defined. + The default is to say the time remaining. + m([class]) - Provide hold music to the calling party until a requested + channel answers. A specific MusicOnHold class can be + specified. + M(x[^arg]) - Execute the Macro for the *called* channel before connecting + to the calling channel. Arguments can be specified to the Macro + using '^' as a delimeter. The Macro can set the variable + MACRO_RESULT to specify the following actions after the Macro is + finished executing. + * ABORT Hangup both legs of the call. + * CONGESTION Behave as if line congestion was encountered. + * BUSY Behave as if a busy signal was encountered. + * CONTINUE Hangup the called party and allow the calling party + to continue dialplan execution at the next priority. + * GOTO:<context>^<exten>^<priority> - Transfer the call to the + specified priority. Optionally, an extension, or + extension and priority can be specified. + You cannot use any additional action post answer options in conjunction + with this option. Also, pbx services are not run on the peer (called) channel, + so you will not be able to set timeouts via the TIMEOUT() function in this macro. + n - This option is a modifier for the screen/privacy mode. It specifies + that no introductions are to be saved in the priv-callerintros + directory. + N - This option is a modifier for the screen/privacy mode. It specifies + that if callerID is present, do not screen the call. + o - Specify that the CallerID that was present on the *calling* channel + be set as the CallerID on the *called* channel. This was the + behavior of Asterisk 1.0 and earlier. + O([x]) - "Operator Services" mode (Zaptel channel to Zaptel channel + only, if specified on non-Zaptel interface, it will be ignored). + When the destination answers (presumably an operator services + station), the originator no longer has control of their line. + They may hang up, but the switch will not release their line + until the destination party hangs up (the operator). Specified + without an arg, or with 1 as an arg, the originator hanging up + will cause the phone to ring back immediately. With a 2 specified, + when the "operator" flashes the trunk, it will ring their phone + back. + p - This option enables screening mode. This is basically Privacy mode + without memory. + P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if + it is provided. The current extension is used if a database + family/key is not specified. + r - Indicate ringing to the calling party. Pass no audio to the calling + party until the called channel has answered. + S(x) - Hang up the call after 'x' seconds *after* the called party has + answered the call. + t - Allow the called party to transfer the calling party by sending the + DTMF sequence defined in features.conf. + T - Allow the calling party to transfer the called party by sending the + DTMF sequence defined in features.conf. + U(x[^arg]) - Execute via Gosub the routine 'x' for the *called* channel before connecting + to the calling channel. Arguments can be specified to the Gosub + using '^' as a delimeter. The Gosub routine can set the variable + GOSUB_RESULT to specify the following actions after the Gosub returns. + * ABORT Hangup both legs of the call. + * CONGESTION Behave as if line congestion was encountered. + * BUSY Behave as if a busy signal was encountered. + * CONTINUE Hangup the called party and allow the calling party + to continue dialplan execution at the next priority. + * GOTO:<context>^<exten>^<priority> - Transfer the call to the + specified priority. Optionally, an extension, or + extension and priority can be specified. + You cannot use any additional action post answer options in conjunction + with this option. Also, pbx services are not run on the peer (called) channel, + so you will not be able to set timeouts via the TIMEOUT() function in this routine. + w - Allow the called party to enable recording of the call by sending + the DTMF sequence defined for one-touch recording in features.conf. + W - Allow the calling party to enable recording of the call by sending + the DTMF sequence defined for one-touch recording in features.conf. + +\end{verbatim} + + +\section{Dictate} +\subsection{Synopsis} +\begin{verbatim} +Virtual Dictation Machine +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Dictate([<base_dir>[|<filename>]]) +Start dictation machine using optional base dir for files. + +\end{verbatim} + + +\section{Directory} +\subsection{Synopsis} +\begin{verbatim} +Provide directory of voicemail extensions +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Directory(vm-context[|dial-context[|options]]): This application will present +the calling channel with a directory of extensions from which they can search +by name. The list of names and corresponding extensions is retrieved from the +voicemail configuration file, voicemail.conf. + This application will immediately exit if one of the following DTMF digits are +received and the extension to jump to exists: + 0 - Jump to the 'o' extension, if it exists. + * - Jump to the 'a' extension, if it exists. + + Parameters: + vm-context - This is the context within voicemail.conf to use for the + Directory. + dial-context - This is the dialplan context to use when looking for an + extension that the user has selected, or when jumping to the + 'o' or 'a' extension. + + Options: + e - In addition to the name, also read the extension number to the + caller before presenting dialing options. + f - Allow the caller to enter the first name of a user in the directory + instead of using the last name. + +\end{verbatim} + + +\section{DISA} +\subsection{Synopsis} +\begin{verbatim} +DISA (Direct Inward System Access) +\end{verbatim} +\subsection{Description} +\begin{verbatim} +DISA(<numeric passcode>[|<context>[|<cid>[|mailbox[|options]]]]) or +DISA(<filename>[||||options]) +The DISA, Direct Inward System Access, application allows someone from +outside the telephone switch (PBX) to obtain an "internal" system +dialtone and to place calls from it as if they were placing a call from +within the switch. +DISA plays a dialtone. The user enters their numeric passcode, followed by +the pound sign (#). If the passcode is correct, the user is then given +system dialtone within <context> on which a call may be placed. If the user +enters an invalid extension and extension "i" exists in the specified +context, it will be used. + +If you need to present a DISA dialtone without entering a password, simply +set <passcode> to "no-password". + +Be aware that using this may compromise the security of your PBX. + +The arguments to this application (in extensions.conf) allow either +specification of a single global passcode (that everyone uses), or +individual passcodes contained in a file. + +The file that contains the passcodes (if used) allows a complete +specification of all of the same arguments available on the command +line, with the sole exception of the options. The file may contain blank +lines, or comments starting with "#" or ";". + +<context> specifies the dialplan context in which the user-entered extension +will be matched. If no context is specified, the DISA application defaults +the context to "disa". Presumably a normal system will have a special +context set up for DISA use with some or a lot of restrictions. + +<cid> specifies a new (different) callerid to be used for this call. + +<mailbox[@context]> will cause a stutter-dialtone (indication "dialrecall") +to be used, if the specified mailbox contains any new messages. + +The following options are available: + n - the DISA application will not answer initially. + p - the extension entered will be considered complete when a '#' is entered. + +\end{verbatim} + + +\section{DumpChan} +\subsection{Synopsis} +\begin{verbatim} +Dump Info About The Calling Channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + DumpChan([<min_verbose_level>]) +Displays information on channel and listing of all channel +variables. If min_verbose_level is specified, output is only +displayed when the verbose level is currently set to that number +or greater. + +\end{verbatim} + + +\section{EAGI} +\subsection{Synopsis} +\begin{verbatim} +Executes an EAGI compliant application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + [E|Dead]AGI(command|args): Executes an Asterisk Gateway Interface compliant +program on a channel. AGI allows Asterisk to launch external programs +written in any language to control a telephony channel, play audio, +read DTMF digits, etc. by communicating with the AGI protocol on stdin +and stdout. + This channel will stop dialplan execution on hangup inside of this +application, except when using DeadAGI. Otherwise, dialplan execution +will continue normally. + A locally executed AGI script will receive SIGHUP on hangup from the channel +except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel +variable to "no" before executing the AGI application. + Using 'EAGI' provides enhanced AGI, with incoming audio available out of band +on file descriptor 3 + + Use the CLI command 'agi show' to list available agi commands + This application sets the following channel variable upon completion: + AGISTATUS The status of the attempt to the run the AGI script + text string, one of SUCCESS | FAILED | NOTFOUND | HANGUP + +\end{verbatim} + + +\section{Echo} +\subsection{Synopsis} +\begin{verbatim} +Echo audio, video, or DTMF back to the calling party +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Echo(): This application will echo any audio, video, or DTMF frames read from +the calling channel back to itself. If the DTMF digit '#' is received, the +application will exit. + +\end{verbatim} + + +\section{EndWhile} +\subsection{Synopsis} +\begin{verbatim} +End a while loop +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: EndWhile() +Return to the previous called While + +\end{verbatim} + + +\section{Exec} +\subsection{Synopsis} +\begin{verbatim} +Executes dialplan application +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: Exec(appname(arguments)) + Allows an arbitrary application to be invoked even when not +hardcoded into the dialplan. If the underlying application +terminates the dialplan, or if the application cannot be found, +Exec will terminate the dialplan. + To invoke external applications, see the application System. + If you would like to catch any error instead, see TryExec. + +\end{verbatim} + + +\section{ExecIf} +\subsection{Synopsis} +\begin{verbatim} +Executes dialplan application, conditionally +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: ExecIF (<expr>|<app>|<data>) +If <expr> is true, execute and return the result of <app>(<data>). +If <expr> is true, but <app> is not found, then the application +will return a non-zero value. + +\end{verbatim} + + +\section{ExecIfTime} +\subsection{Synopsis} +\begin{verbatim} +Conditional application execution based on the current time +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ExecIfTime(<times>|<weekdays>|<mdays>|<months>?appname[|appargs]): +This application will execute the specified dialplan application, with optional +arguments, if the current time matches the given time specification. + +\end{verbatim} + + +\section{ExitWhile} +\subsection{Synopsis} +\begin{verbatim} +End a While loop +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: ExitWhile() +Exits a While loop, whether or not the conditional has been satisfied. + +\end{verbatim} + + +\section{ExtenSpy} +\subsection{Synopsis} +\begin{verbatim} +Listen to a channel, and optionally whisper into it +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ExtenSpy(exten[@context][|options]): This application is used to listen to the +audio from an Asterisk channel. This includes the audio coming in and +out of the channel being spied on. Only channels created by outgoing calls for the +specified extension will be selected for spying. If the optional context is not +supplied, the current channel's context will be used. + While spying, the following actions may be performed: + - Dialing # cycles the volume level. + - Dialing * will stop spying and look for another channel to spy on. + Note: The X option superseeds the two features above in that if a valid + single digit extension exists in the correct context it ChanSpy will + exit to it. + Options: + b - Only spy on channels involved in a bridged call. + g(grp) - Match only channels where their ${SPYGROUP} variable is set to + contain 'grp' in an optional : delimited list. + q - Don't play a beep when beginning to spy on a channel, or speak the + selected channel name. + r[(basename)] - Record the session to the monitor spool directory. An + optional base for the filename may be specified. The + default is 'chanspy'. + v([value]) - Adjust the initial volume in the range from -4 to 4. A + negative value refers to a quieter setting. + w - Enable 'whisper' mode, so the spying channel can talk to + the spied-on channel. + W - Enable 'private whisper' mode, so the spying channel can + talk to the spied-on channel but cannot listen to that + channel. + o - Only listen to audio coming from this channel. + X - Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the SPY_EXIT_CONTEXT channel variable. The + name of the last channel that was spied on will be stored + in the SPY_CHANNEL variable. + +\end{verbatim} + + +\section{ExternalIVR} +\subsection{Synopsis} +\begin{verbatim} +Interfaces with an external IVR application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ExternalIVR(command[|arg[|arg...]]): Forks an process to run the supplied command, +and starts a generator on the channel. The generator's play list is +controlled by the external application, which can add and clear entries +via simple commands issued over its stdout. The external application +will receive all DTMF events received on the channel, and notification +if the channel is hung up. The application will not be forcibly terminated +when the channel is hung up. +See doc/externalivr.txt for a protocol specification. + +\end{verbatim} + + +\section{Festival} +\subsection{Synopsis} +\begin{verbatim} +Say text to the user +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Festival(text[|intkeys]): Connect to Festival, send the argument, get back the waveform,play it to the user, allowing any given interrupt keys to immediately terminate and return +the value, or 'any' to allow any number back (useful in dialplan) + +\end{verbatim} + + +\section{Flash} +\subsection{Synopsis} +\begin{verbatim} +Flashes a Zap Trunk +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Flash(): Sends a flash on a zap trunk. This is only a hack for +people who want to perform transfers and such via AGI and is generally +quite useless oths application will only work on Zap trunks. + +\end{verbatim} + + +\section{FollowMe} +\subsection{Synopsis} +\begin{verbatim} +Find-Me/Follow-Me application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + FollowMe(followmeid|options): +This application performs Find-Me/Follow-Me functionality for the caller +as defined in the profile matching the <followmeid> parameter in +followme.conf. If the specified <followmeid> profile doesn't exist in +followme.conf, execution will be returned to the dialplan and call +execution will continue at the next priority. + + Options: + s - Playback the incoming status message prior to starting the follow-me step(s) + a - Record the caller's name so it can be announced to the callee on each step + n - Playback the unreachable status message if we've run out of steps to reach the + or the callee has elected not to be reachable. +Returns -1 on hangup + +\end{verbatim} + + +\section{ForkCDR} +\subsection{Synopsis} +\begin{verbatim} +Forks the Call Data Record +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ForkCDR([options]): Causes the Call Data Record to fork an additional +cdr record starting from the time of the fork call +If the option 'v' is passed all cdr variables will be passed along also. + +\end{verbatim} + + +\section{GetCPEID} +\subsection{Synopsis} +\begin{verbatim} +Get ADSI CPE ID +\end{verbatim} +\subsection{Description} +\begin{verbatim} + GetCPEID: Obtains and displays ADSI CPE ID and other information in order +to properly setup zapata.conf for on-hook operations. + +\end{verbatim} + + +\section{Gosub} +\subsection{Synopsis} +\begin{verbatim} +Jump to label, saving return address +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gosub([[context|]exten|]priority[(arg1[|...][|argN])]) + Jumps to the label specified, saving the return address. + +\end{verbatim} + + +\section{GosubIf} +\subsection{Synopsis} +\begin{verbatim} +Conditionally jump to label, saving return address +\end{verbatim} +\subsection{Description} +\begin{verbatim} +GosubIf(condition?labeliftrue[(arg1[|...])][:labeliffalse[(arg1[|...])]]) + If the condition is true, then jump to labeliftrue. If false, jumps to +labeliffalse, if specified. In either case, a jump saves the return point +in the dialplan, to be returned to with a Return. + +\end{verbatim} + + +\section{Goto} +\subsection{Synopsis} +\begin{verbatim} +Jump to a particular priority, extension, or context +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Goto([[context|]extension|]priority): This application will set the current +context, extension, and priority in the channel structure. After it completes, the +pbx engine will continue dialplan execution at the specified location. +If no specific extension, or extension and context, are specified, then this +application will just set the specified priority of the current extension. + At least a priority is required as an argument, or the goto will return a -1, +and the channel and call will be terminated. + If the location that is put into the channel information is bogus, and asterisk cannot +find that location in the dialplan, +then the execution engine will try to find and execute the code in the 'i' (invalid) +extension in the current context. If that does not exist, it will try to execute the +'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the +channel is hung up, and the execution of instructions on the channel is terminated. +What this means is that, for example, you specify a context that does not exist, then +it will not be possible to find the 'h' or 'i' extensions, and the call will terminate! + +\end{verbatim} + + +\section{GotoIf} +\subsection{Synopsis} +\begin{verbatim} +Conditional goto +\end{verbatim} +\subsection{Description} +\begin{verbatim} + GotoIf(condition?[labeliftrue]:[labeliffalse]): This application will set the current +context, extension, and priority in the channel structure based on the evaluation of +the given condition. After this application completes, the +pbx engine will continue dialplan execution at the specified location in the dialplan. +The channel will continue at +'labeliftrue' if the condition is true, or 'labeliffalse' if the condition is +false. The labels are specified with the same syntax as used within the Goto +application. If the label chosen by the condition is omitted, no jump is +performed, and the execution passes to the next instruction. +If the target location is bogus, and does not exist, the execution engine will try +to find and execute the code in the 'i' (invalid) +extension in the current context. If that does not exist, it will try to execute the +'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the +channel is hung up, and the execution of instructions on the channel is terminated. +Remember that this command can set the current context, and if the context specified +does not exist, then it will not be able to find any 'h' or 'i' extensions there, and +the channel and call will both be terminated! + +\end{verbatim} + + +\section{GotoIfTime} +\subsection{Synopsis} +\begin{verbatim} +Conditional Goto based on the current time +\end{verbatim} +\subsection{Description} +\begin{verbatim} + GotoIfTime(<times>|<weekdays>|<mdays>|<months>?[[context|]exten|]priority): +This application will set the context, extension, and priority in the channel structure +if the current time matches the given time specification. Otherwise, nothing is done. +Further information on the time specification can be found in examples +illustrating how to do time-based context includes in the dialplan. +If the target jump location is bogus, the same actions would be taken as for Goto. + +\end{verbatim} + + +\section{Hangup} +\subsection{Synopsis} +\begin{verbatim} +Hang up the calling channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Hangup([causecode]): This application will hang up the calling channel. +If a causecode is given the channel's hangup cause will be set to the given +value. + +\end{verbatim} + + +\section{IAX2Provision} +\subsection{Synopsis} +\begin{verbatim} +Provision a calling IAXy with a given template +\end{verbatim} +\subsection{Description} +\begin{verbatim} + IAX2Provision([template]): Provisions the calling IAXy (assuming +the calling entity is in fact an IAXy) with the given template or +default if one is not specified. Returns -1 on error or 0 on success. + +\end{verbatim} + + +\section{ICES} +\subsection{Synopsis} +\begin{verbatim} +Encode and stream using 'ices' +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ICES(config.xml) Streams to an icecast server using ices +(available separately). A configuration file must be supplied +for ices (see examples/asterisk-ices.conf). + +\end{verbatim} + + +\section{ImportVar} +\subsection{Synopsis} +\begin{verbatim} +Import a variable from a channel into a new variable +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ImportVar(newvar=channelname|variable): This application imports a variable +from the specified channel (as opposed to the current one) and stores it as +a variable in the current channel (the channel that is calling this +application). Variables created by this application have the same inheritance +properties as those created with the Set application. See the documentation for +Set for more information. + +\end{verbatim} + + +\section{IVRDemo} +\subsection{Synopsis} +\begin{verbatim} +IVR Demo Application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + This is a skeleton application that shows you the basic structure to create your +own asterisk applications and demonstrates the IVR demo. + +\end{verbatim} + + +\section{JabberSend} +\subsection{Synopsis} +\begin{verbatim} +JabberSend(jabber,screenname,message) +\end{verbatim} +\subsection{Description} +\begin{verbatim} +JabberSend(Jabber,ScreenName,Message) + Jabber - Client or transport Asterisk uses to connect to Jabber + ScreenName - User Name to message. + Message - Message to be sent to the buddy + +\end{verbatim} + + +\section{JabberStatus} +\subsection{Synopsis} +\begin{verbatim} +JabberStatus(Jabber,ScreenName,Variable) +\end{verbatim} +\subsection{Description} +\begin{verbatim} +JabberStatus(Jabber,ScreenName,Variable) + Jabber - Client or transport Asterisk uses to connect to Jabber + ScreenName - User Name to retrieve status from. + Variable - Variable to store presence in will be 1-6. + In order, Online, Chatty, Away, XAway, DND, Offline + If not in roster variable will = 7 + +\end{verbatim} + + +\section{KeepAlive} +\subsection{Synopsis} +\begin{verbatim} +returns AST_PBX_KEEPALIVE value +\end{verbatim} +\subsection{Description} +\begin{verbatim} + KeepAlive(): This application is chiefly meant for internal use with Gosubs. +Please do not run it alone from the dialplan! + +\end{verbatim} + + +\section{Log} +\subsection{Synopsis} +\begin{verbatim} +Send arbitrary text to a selected log level +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Log(<level>|<message>) + level must be one of ERROR, WARNING, NOTICE, DEBUG, VERBOSE, DTMF + +\end{verbatim} + + +\section{Macro} +\subsection{Synopsis} +\begin{verbatim} +Macro Implementation +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Macro(macroname|arg1|arg2...): Executes a macro using the context +'macro-<macroname>', jumping to the 's' extension of that context and +executing each step, then returning when the steps end. +The calling extension, context, and priority are stored in ${MACRO_EXTEN}, +${MACRO_CONTEXT} and ${MACRO_PRIORITY} respectively. Arguments become +${ARG1}, ${ARG2}, etc in the macro context. +If you Goto out of the Macro context, the Macro will terminate and control +will be returned at the location of the Goto. +If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue +at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise. +Extensions: While a macro is being executed, it becomes the current context. + This means that if a hangup occurs, for instance, that the macro + will be searched for an 'h' extension, NOT the context from which + the macro was called. So, make sure to define all appropriate + extensions in your macro! (Note: AEL does not use macros) +WARNING: Because of the way Macro is implemented (it executes the priorities + contained within it via sub-engine), and a fixed per-thread + memory stack allowance, macros are limited to 7 levels + of nesting (macro calling macro calling macro, etc.); It + may be possible that stack-intensive applications in deeply nested macros + could cause asterisk to crash earlier than this limit. It is advised that + if you need to deeply nest macro calls, that you use the Gosub application + (now allows arguments like a Macro) with explict Return() calls instead. + +\end{verbatim} + + +\section{MacroExclusive} +\subsection{Synopsis} +\begin{verbatim} +Exclusive Macro Implementation +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MacroExclusive(macroname|arg1|arg2...): +Executes macro defined in the context 'macro-macroname' +Only one call at a time may run the macro. +(we'll wait if another call is busy executing in the Macro) +Arguments and return values as in application Macro() + +\end{verbatim} + + +\section{MacroExit} +\subsection{Synopsis} +\begin{verbatim} +Exit From Macro +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MacroExit(): +Causes the currently running macro to exit as if it had +ended normally by running out of priorities to execute. +If used outside a macro, will likely cause unexpected +behavior. + +\end{verbatim} + + +\section{MacroIf} +\subsection{Synopsis} +\begin{verbatim} +Conditional Macro Implementation +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MacroIf(<expr>?macroname_a[|arg1][:macroname_b[|arg1]]) +Executes macro defined in <macroname_a> if <expr> is true +(otherwise <macroname_b> if provided) +Arguments and return values as in application macro() + +\end{verbatim} + + +\section{MailboxExists} +\subsection{Synopsis} +\begin{verbatim} +Check to see if Voicemail mailbox exists +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MailboxExists(mailbox[@context][|options]): Check to see if the specified +mailbox exists. If no voicemail context is specified, the 'default' context +will be used. + This application will set the following channel variable upon completion: + VMBOXEXISTSSTATUS - This will contain the status of the execution of the + MailboxExists application. Possible values include: + SUCCESS | FAILED + + Options: (none) + +\end{verbatim} + + +\section{MeetMe} +\subsection{Synopsis} +\begin{verbatim} +MeetMe conference bridge +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MeetMe([confno][,[options][,pin]]): Enters the user into a specified MeetMe +conference. If the conference number is omitted, the user will be prompted +to enter one. User can exit the conference by hangup, or if the 'p' option +is specified, by pressing '#'. +Please note: The Zaptel kernel modules and at least one hardware driver (or ztdummy) + must be present for conferencing to operate properly. In addition, the chan_zap + channel driver must be loaded for the 'i' and 'r' options to operate at all. + +The option string may contain zero or more of the following characters: + 'a' -- set admin mode + 'A' -- set marked mode + 'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND} + Default: conf-background.agi (Note: This does not work with + non-Zap channels in the same conference) + 'c' -- announce user(s) count on joining a conference + 'C' -- continue in dialplan when kicked out of conference + 'd' -- dynamically add conference + 'D' -- dynamically add conference, prompting for a PIN + 'e' -- select an empty conference + 'E' -- select an empty pinless conference + 'F' -- Pass DTMF through the conference. DTMF used to activate any + conference features will not be passed through. + 'i' -- announce user join/leave with review + 'I' -- announce user join/leave without review + 'l' -- set listen only mode (Listen only, no talking) + 'm' -- set initially muted + 'M' -- enable music on hold when the conference has a single caller + 'o' -- set talker optimization - treats talkers who aren't speaking as + being muted, meaning (a) No encode is done on transmission and + (b) Received audio that is not registered as talking is omitted + causing no buildup in background noise + 'p' -- allow user to exit the conference by pressing '#' + 'P' -- always prompt for the pin even if it is specified + 'q' -- quiet mode (don't play enter/leave sounds) + 'r' -- Record conference (records as ${MEETME_RECORDINGFILE} + using format ${MEETME_RECORDINGFORMAT}). Default filename is + meetme-conf-rec-${CONFNO}-${UNIQUEID} and the default format is + wav. + 's' -- Present menu (user or admin) when '*' is received ('send' to menu) + 't' -- set talk only mode. (Talk only, no listening) + 'T' -- set talker detection (sent to manager interface and meetme list) + 'w[(<secs>)]' + -- wait until the marked user enters the conference + 'x' -- close the conference when last marked user exits + 'X' -- allow user to exit the conference by entering a valid single + digit extension ${MEETME_EXIT_CONTEXT} or the current context + if that variable is not defined. + '1' -- do not play message when first person enters + +\end{verbatim} + + +\section{MeetMeAdmin} +\subsection{Synopsis} +\begin{verbatim} +MeetMe conference Administration +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MeetMeAdmin(confno,command[,user]): Run admin command for conference + 'e' -- Eject last user that joined + 'k' -- Kick one user out of conference + 'K' -- Kick all users out of conference + 'l' -- Unlock conference + 'L' -- Lock conference + 'm' -- Unmute one user + 'M' -- Mute one user + 'n' -- Unmute all users in the conference + 'N' -- Mute all non-admin users in the conference + 'r' -- Reset one user's volume settings + 'R' -- Reset all users volume settings + 's' -- Lower entire conference speaking volume + 'S' -- Raise entire conference speaking volume + 't' -- Lower one user's talk volume + 'T' -- Raise one user's talk volume + 'u' -- Lower one user's listen volume + 'U' -- Raise one user's listen volume + 'v' -- Lower entire conference listening volume + 'V' -- Raise entire conference listening volume + +\end{verbatim} + + +\section{MeetMeChannelAdmin} +\subsection{Synopsis} +\begin{verbatim} +MeetMe conference Administration (channel specific) +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MeetMeChannelAdmin(channel|command): Run admin command for a specific +channel in any coference. + 'k' -- Kick the specified user out of the conference he is in + 'm' -- Unmute the specified user + 'M' -- Mute the specified user + +\end{verbatim} + + +\section{MeetMeCount} +\subsection{Synopsis} +\begin{verbatim} +MeetMe participant count +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MeetMeCount(confno[|var]): Plays back the number of users in the specified +MeetMe conference. If var is specified, playback will be skipped and the value +will be returned in the variable. Upon app completion, MeetMeCount will hangup +the channel, unless priority n+1 exists, in which case priority progress will +continue. +A ZAPTEL INTERFACE MUST BE INSTALLED FOR CONFERENCING FUNCTIONALITY. + +\end{verbatim} + + +\section{Milliwatt} +\subsection{Synopsis} +\begin{verbatim} +Generate a Constant 1000Hz tone at 0dbm (mu-law) +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Milliwatt(): Generate a Constant 1000Hz tone at 0dbm (mu-law) + +\end{verbatim} + + +\section{MinivmAccMess} +\subsection{Synopsis} +\begin{verbatim} +Record account specific messages +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmAccmess(username@domain,option) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +Use this application to record account specific audio/video messages for +busy, unavailable and temporary messages. +Account specific directories will be created if they do not exist. + +The option selects message to be recorded: + u Unavailable + b Busy + t Temporary (overrides busy and unavailable) + n Account name + +Result is given in channel variable MINIVM_ACCMESS_STATUS + The possible values are: SUCCESS | FAILED + FAILED is set if the file can't be created. + + +\end{verbatim} + + +\section{MinivmDelete} +\subsection{Synopsis} +\begin{verbatim} +Delete Mini-Voicemail voicemail messages +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmDelete(filename) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +It deletes voicemail file set in MVM_FILENAME or given filename. + +Result is given in channel variable MINIVM_DELETE_STATUS + The possible values are: SUCCESS | FAILED + FAILED is set if the file does not exist or can't be deleted. + + +\end{verbatim} + + +\section{MinivmGreet} +\subsection{Synopsis} +\begin{verbatim} +Play Mini-Voicemail prompts +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmGreet(username@domain[,options]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MinivmGreet() plays default prompts or user specific prompts for an account. +Busy and unavailable messages can be choosen, but will be overridden if a temporary +message exists for the account. + +Result is given in channel variable MINIVM_GREET_STATUS + The possible values are: SUCCESS | USEREXIT | FAILED + + Options: + b - Play the 'busy' greeting to the calling party. + s - Skip the playback of instructions for leaving a message to the + calling party. + u - Play the 'unavailable greeting. + + +\end{verbatim} + + +\section{MinivmNotify} +\subsection{Synopsis} +\begin{verbatim} +Notify voicemail owner about new messages. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmNotify(username@domain[,template]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MiniVMnotify forwards messages about new voicemail to e-mail and pager. +If there's no user account for that address, a temporary account will +be used with default options (set in minivm.conf). +The recorded file name and path will be read from MVM_FILENAME and the +duration of the message will be accessed from MVM_DURATION (set by MinivmRecord() ) +If the channel variable MVM_COUNTER is set, this will be used in the +message file name and available in the template for the message. +If not template is given, the default email template will be used to send email and +default pager template to send paging message (if the user account is configured with +a paging address. + +Result is given in channel variable MINIVM_NOTIFY_STATUS + The possible values are: SUCCESS | FAILED + + +\end{verbatim} + + +\section{MinivmRecord} +\subsection{Synopsis} +\begin{verbatim} +Receive Mini-Voicemail and forward via e-mail +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Syntax: MinivmRecord(username@domain[,options]) +This application is part of the Mini-Voicemail system, configured in minivm.conf. +MiniVM records audio file in configured format and forwards message to e-mail and pager. +If there's no user account for that address, a temporary account will +be used with default options. +The recorded file name and path will be stored in MINIVM_FILENAME and the +duration of the message will be stored in MINIVM_DURATION + +Note: If the caller hangs up after the recording, the only way to send +the message and clean up is to execute in the "h" extension. + +The application will exit if any of the following DTMF digits are +received and the requested extension exist in the current context. + 0 - Jump to the 'o' extension in the current dialplan context. + * - Jump to the 'a' extension in the current dialplan context. + +Result is given in channel variable MINIVM_RECORD_STATUS + The possible values are: SUCCESS | USEREXIT | FAILED + + Options: + g(#) - Use the specified amount of gain when recording the voicemail + message. The units are whole-number decibels (dB). + + +\end{verbatim} + + +\section{MixMonitor} +\subsection{Synopsis} +\begin{verbatim} +Record a call and mix the audio during the recording +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MixMonitor(<file>.<ext>[|<options>[|<command>]]) + +Records the audio on the current channel to the specified file. +If the filename is an absolute path, uses that path, otherwise +creates the file in the configured monitoring directory from +asterisk.conf. + +Valid options: + a - Append to the file instead of overwriting it. + b - Only save audio to the file while the channel is bridged. + Note: Does not include conferences or sounds played to each bridged + party. + v(<x>) - Adjust the heard volume by a factor of <x> (range -4 to 4) + V(<x>) - Adjust the spoken volume by a factor of <x> (range -4 to 4) + W(<x>) - Adjust the both heard and spoken volumes by a factor of <x> + (range -4 to 4) + +<command> will be executed when the recording is over +Any strings matching ^{X} will be unescaped to ${X}. +All variables will be evaluated at the time MixMonitor is called. +The variable MIXMONITOR_FILENAME will contain the filename used to record. + +\end{verbatim} + + +\section{Monitor} +\subsection{Synopsis} +\begin{verbatim} +Monitor a channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Monitor([file_format[:urlbase]|[fname_base]|[options]]): +Used to start monitoring a channel. The channel's input and output +voice packets are logged to files until the channel hangs up or +monitoring is stopped by the StopMonitor application. + file_format optional, if not set, defaults to "wav" + fname_base if set, changes the filename used to the one specified. + options: + m - when the recording ends mix the two leg files into one and + delete the two leg files. If the variable MONITOR_EXEC is set, the + application referenced in it will be executed instead of + soxmix and the raw leg files will NOT be deleted automatically. + soxmix or MONITOR_EXEC is handed 3 arguments, the two leg files + and a target mixed file name which is the same as the leg file names + only without the in/out designator. + If MONITOR_EXEC_ARGS is set, the contents will be passed on as + additional arguements to MONITOR_EXEC + Both MONITOR_EXEC and the Mix flag can be set from the + administrator interface + + b - Don't begin recording unless a call is bridged to another channel + +Returns -1 if monitor files can't be opened or if the channel is already +monitored, otherwise 0. + +\end{verbatim} + + +\section{Morsecode} +\subsection{Synopsis} +\begin{verbatim} +Plays morse code +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: Morsecode(<string>) +Plays the Morse code equivalent of the passed string. If the variable +MORSEDITLEN is set, it will use that value for the length (in ms) of the dit +(defaults to 80). Additionally, if MORSETONE is set, it will use that tone +(in Hz). The tone default is 800. + +\end{verbatim} + + +\section{MP3Player} +\subsection{Synopsis} +\begin{verbatim} +Play an MP3 file or stream +\end{verbatim} +\subsection{Description} +\begin{verbatim} + MP3Player(location) Executes mpg123 to play the given location, +which typically would be a filename or a URL. User can exit by pressing +any key on the dialpad, or by hanging up. +\end{verbatim} + + +\section{MusicOnHold} +\subsection{Synopsis} +\begin{verbatim} +Play Music On Hold indefinitely +\end{verbatim} +\subsection{Description} +\begin{verbatim} +MusicOnHold(class): Plays hold music specified by class. If omitted, the default +music source for the channel will be used. Set the default +class with the SetMusicOnHold() application. +Returns -1 on hangup. +Never returns otherwise. + +\end{verbatim} + + +\section{NBScat} +\subsection{Synopsis} +\begin{verbatim} +Play an NBS local stream +\end{verbatim} +\subsection{Description} +\begin{verbatim} + NBScat: Executes nbscat to listen to the local NBS stream. +User can exit by pressing any key +. +\end{verbatim} + + +\section{NoCDR} +\subsection{Synopsis} +\begin{verbatim} +Tell Asterisk to not maintain a CDR for the current call +\end{verbatim} +\subsection{Description} +\begin{verbatim} + NoCDR(): This application will tell Asterisk not to maintain a CDR for the +current call. + +\end{verbatim} + + +\section{NoOp} +\subsection{Synopsis} +\begin{verbatim} +Do Nothing +\end{verbatim} +\subsection{Description} +\begin{verbatim} + NoOp(): This applicatiion does nothing. However, it is useful for debugging +purposes. Any text that is provided as arguments to this application can be +viewed at the Asterisk CLI. This method can be used to see the evaluations of +variables or functions without having any effect. +\end{verbatim} + + +\section{ODBCFinish} +\subsection{Synopsis} +\begin{verbatim} +Clear the resultset of a successful multirow query +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ODBCFinish(<result-id>) + Clears any remaining rows of the specified resultset + +\end{verbatim} + + +\section{Page} +\subsection{Synopsis} +\begin{verbatim} +Pages phones +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Page(Technology/Resource&Technology2/Resource2[|options]) + Places outbound calls to the given technology / resource and dumps +them into a conference bridge as muted participants. The original +caller is dumped into the conference as a speaker and the room is +destroyed when the original caller leaves. Valid options are: + d - full duplex audio + q - quiet, do not play beep to caller + r - record the page into a file (see 'r' for app_meetme) + s - only dial channel if devicestate says it is not in use + +\end{verbatim} + + +\section{Park} +\subsection{Synopsis} +\begin{verbatim} +Park yourself +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Park():Used to park yourself (typically in combination with a supervised +transfer to know the parking space). This application is always +registered internally and does not need to be explicitly added +into the dialplan, although you should include the 'parkedcalls' +context (or the context specified in features.conf). + +If you set the PARKINGEXTEN variable to an extension in your +parking context, park() will park the call on that extension, unless +it already exists. In that case, execution will continue at next +priority. + +\end{verbatim} + + +\section{ParkAndAnnounce} +\subsection{Synopsis} +\begin{verbatim} +Park and Announce +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ParkAndAnnounce(announce:template|timeout|dial|[return_context]): +Park a call into the parkinglot and announce the call to another channel. + +announce template: Colon-separated list of files to announce. The word PARKED + will be replaced by a say_digits of the extension in which + the call is parked. +timeout: Time in seconds before the call returns into the return + context. +dial: The app_dial style resource to call to make the + announcement. Console/dsp calls the console. +return_context: The goto-style label to jump the call back into after + timeout. Default <priority+1>. + +The variable ${PARKEDAT} will contain the parking extension into which the +call was placed. Use with the Local channel to allow the dialplan to make +use of this information. + +\end{verbatim} + + +\section{ParkedCall} +\subsection{Synopsis} +\begin{verbatim} +Answer a parked call +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ParkedCall(exten):Used to connect to a parked call. This application is always +registered internally and does not need to be explicitly added +into the dialplan, although you should include the 'parkedcalls' +context. + +\end{verbatim} + + +\section{PauseMonitor} +\subsection{Synopsis} +\begin{verbatim} +Pause monitoring of a channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +PauseMonitor +Pauses monitoring of a channel until it is re-enabled by a call to UnpauseMonitor. + +\end{verbatim} + + +\section{PauseQueueMember} +\subsection{Synopsis} +\begin{verbatim} +Pauses a queue member +\end{verbatim} +\subsection{Description} +\begin{verbatim} + PauseQueueMember([queuename]|interface[|options]): +Pauses (blocks calls for) a queue member. +The given interface will be paused in the given queue. This prevents +any calls from being sent from the queue to the interface until it is +unpaused with UnpauseQueueMember or the manager interface. If no +queuename is given, the interface is paused in every queue it is a +member of. The application will fail if the interface is not found. + This application sets the following channel variable upon completion: + PQMSTATUS The status of the attempt to pause a queue member as a + text string, one of + PAUSED | NOTFOUND +Example: PauseQueueMember(|SIP/3000) + +\end{verbatim} + + +\section{Pickup} +\subsection{Synopsis} +\begin{verbatim} +Directed Call Pickup +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Pickup(extension[@context][&extension2@context...]): This application can pickup any ringing channel +that is calling the specified extension. If no context is specified, the current +context will be used. If you use the special string "PICKUPMARK" for the context parameter, for example +10@PICKUPMARK, this application tries to find a channel which has defined a channel variable with the same content +as "extension". +\end{verbatim} + + +\section{Playback} +\subsection{Synopsis} +\begin{verbatim} +Play a file +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Playback(filename[&filename2...][|option]): Plays back given filenames (do not put +extension). Options may also be included following a pipe symbol. The 'skip' +option causes the playback of the message to be skipped if the channel +is not in the 'up' state (i.e. it hasn't been answered yet). If 'skip' is +specified, the application will return immediately should the channel not be +off hook. Otherwise, unless 'noanswer' is specified, the channel will +be answered before the sound is played. Not all channels support playing +messages while still on hook. +This application sets the following channel variable upon completion: + PLAYBACKSTATUS The status of the playback attempt as a text string, one of + SUCCESS | FAILED + +\end{verbatim} + + +\section{PlayTones} +\subsection{Synopsis} +\begin{verbatim} +Play a tone list +\end{verbatim} +\subsection{Description} +\begin{verbatim} +PlayTones(arg): Plays a tone list. Execution will continue with the next step immediately, +while the tones continue to play. +Arg is either the tone name defined in the indications.conf configuration file, or a directly +specified list of frequencies and durations. +See the sample indications.conf for a description of the specification of a tonelist. + +Use the StopPlayTones application to stop the tones playing. + +\end{verbatim} + + +\section{PrivacyManager} +\subsection{Synopsis} +\begin{verbatim} +Require phone number to be entered, if no CallerID sent +\end{verbatim} +\subsection{Description} +\begin{verbatim} + PrivacyManager([maxretries[|minlength[|options]]]): If no Caller*ID +is sent, PrivacyManager answers the channel and asks the caller to +enter their phone number. The caller is given 3 attempts to do so. +The application does nothing if Caller*ID was received on the channel. + Configuration file privacy.conf contains two variables: + maxretries default 3 -maximum number of attempts the caller is allowed + to input a callerid. + minlength default 10 -minimum allowable digits in the input callerid number. +If you don't want to use the config file and have an i/o operation with +every call, you can also specify maxretries and minlength as application +parameters. Doing so supercedes any values set in privacy.conf. +The application sets the following channel variable upon completion: +PRIVACYMGRSTATUS The status of the privacy manager's attempt to collect + a phone number from the user. A text string that is either: + SUCCESS | FAILED + +\end{verbatim} + + +\section{Progress} +\subsection{Synopsis} +\begin{verbatim} +Indicate progress +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Progress(): This application will request that in-band progress information +be provided to the calling channel. + +\end{verbatim} + + +\section{Queue} +\subsection{Synopsis} +\begin{verbatim} +Queue a call for a call queue +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Queue(queuename[|options[|URL][|announceoverride][|timeout][|AGI][|macro][|gosub]): +Queues an incoming call in a particular call queue as defined in queues.conf. +This application will return to the dialplan if the queue does not exist, or +any of the join options cause the caller to not enter the queue. +The option string may contain zero or more of the following characters: + 'c' -- continue in the dialplan if the callee hangs up. + 'd' -- data-quality (modem) call (minimum delay). + 'h' -- allow callee to hang up by pressing *. + 'H' -- allow caller to hang up by pressing *. + 'n' -- no retries on the timeout; will exit this application and + go to the next step. + 'i' -- ignore call forward requests from queue members and do nothing + when they are requested. + 'r' -- ring instead of playing MOH. + 't' -- allow the called user to transfer the calling user. + 'T' -- allow the calling user to transfer the call. + 'w' -- allow the called user to write the conversation to disk via Monitor. + 'W' -- allow the calling user to write the conversation to disk via Monitor. + In addition to transferring the call, a call may be parked and then picked +up by another user. + The optional URL will be sent to the called party if the channel supports +it. + The optional AGI parameter will setup an AGI script to be executed on the +calling party's channel once they are connected to a queue member. + The optional macro parameter will run a macro on the +calling party's channel once they are connected to a queue member. + The optional gosub parameter will run a gosub on the +calling party's channel once they are connected to a queue member. + The timeout will cause the queue to fail out after a specified number of +seconds, checked between each queues.conf 'timeout' and 'retry' cycle. + This application sets the following channel variable upon completion: + QUEUESTATUS The status of the call as a text string, one of + TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL | CONTINUE + +\end{verbatim} + + +\section{QueueLog} +\subsection{Synopsis} +\begin{verbatim} +Writes to the queue_log +\end{verbatim} +\subsection{Description} +\begin{verbatim} + QueueLog(queuename|uniqueid|agent|event[|additionalinfo]): +Allows you to write your own events into the queue log +Example: QueueLog(101|${UNIQUEID}|${AGENT}|WENTONBREAK|600) + +\end{verbatim} + + +\section{Read} +\subsection{Synopsis} +\begin{verbatim} +Read a variable +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Read(variable[|filename[&filename2...]][|maxdigits][|option][|attempts][|timeout]) + +Reads a #-terminated string of digits a certain number of times from the +user in to the given variable. + filename -- file(s) to play before reading digits or tone with option i + maxdigits -- maximum acceptable number of digits. Stops reading after + maxdigits have been entered (without requiring the user to + press the '#' key). + Defaults to 0 - no limit - wait for the user press the '#' key. + Any value below 0 means the same. Max accepted value is 255. + option -- options are 's' , 'i', 'n' + 's' to return immediately if the line is not up, + 'i' to play filename as an indication tone from your indications.conf + 'n' to read digits even if the line is not up. + attempts -- if greater than 1, that many attempts will be made in the + event no data is entered. + timeout -- The number of seconds to wait for a digit response. If greater + than 0, that value will override the default timeout. Can be floating point. + +Read should disconnect if the function fails or errors out. + +\end{verbatim} + + +\section{ReadFile} +\subsection{Synopsis} +\begin{verbatim} +ReadFile(varname=file,length) +\end{verbatim} +\subsection{Description} +\begin{verbatim} +ReadFile(varname=file,length) + Varname - Result stored here. + File - The name of the file to read. + Length - Maximum number of characters to capture. + +\end{verbatim} + + +\section{Record} +\subsection{Synopsis} +\begin{verbatim} +Record to a file +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Record(filename.format|silence[|maxduration][|options]) + +Records from the channel into a given filename. If the file exists it will +be overwritten. +- 'format' is the format of the file type to be recorded (wav, gsm, etc). +- 'silence' is the number of seconds of silence to allow before returning. +- 'maxduration' is the maximum recording duration in seconds. If missing +or 0 there is no maximum. +- 'options' may contain any of the following letters: + 'a' : append to existing recording rather than replacing + 'n' : do not answer, but record anyway if line not yet answered + 'q' : quiet (do not play a beep tone) + 's' : skip recording if the line is not yet answered + 't' : use alternate '*' terminator key (DTMF) instead of default '#' + 'x' : ignore all terminator keys (DTMF) and keep recording until hangup + +If filename contains '%d', these characters will be replaced with a number +incremented by one each time the file is recorded. A channel variable +named RECORDED_FILE will also be set, which contains the final filemname. + +Use 'core show file formats' to see the available formats on your system + +User can press '#' to terminate the recording and continue to the next priority. + +If the user should hangup during a recording, all data will be lost and the +application will teminate. + +\end{verbatim} + + +\section{RemoveQueueMember} +\subsection{Synopsis} +\begin{verbatim} +Dynamically removes queue members +\end{verbatim} +\subsection{Description} +\begin{verbatim} + RemoveQueueMember(queuename[|interface[|options]]): +Dynamically removes interface to an existing queue +If the interface is NOT in the queue it will return an error. + This application sets the following channel variable upon completion: + RQMSTATUS The status of the attempt to remove a queue member as a + text string, one of + REMOVED | NOTINQUEUE | NOSUCHQUEUE +Example: RemoveQueueMember(techsupport|SIP/3000) + +\end{verbatim} + + +\section{ResetCDR} +\subsection{Synopsis} +\begin{verbatim} +Resets the Call Data Record +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ResetCDR([options]): This application causes the Call Data Record to be +reset. + Options: + w -- Store the current CDR record before resetting it. + a -- Store any stacked records. + v -- Save CDR variables. + +\end{verbatim} + + +\section{RetryDial} +\subsection{Synopsis} +\begin{verbatim} +Place a call, retrying on failure allowing optional exit extension. +\end{verbatim} +\subsection{Description} +\begin{verbatim} + RetryDial(announce|sleep|retries|dialargs): This application will attempt to +place a call using the normal Dial application. If no channel can be reached, +the 'announce' file will be played. Then, it will wait 'sleep' number of +seconds before retying the call. After 'retires' number of attempts, the +calling channel will continue at the next priority in the dialplan. If the +'retries' setting is set to 0, this application will retry endlessly. + While waiting to retry a call, a 1 digit extension may be dialed. If that +extension exists in either the context defined in ${EXITCONTEXT} or the current +one, The call will jump to that extension immediately. + The 'dialargs' are specified in the same format that arguments are provided +to the Dial application. + +\end{verbatim} + + +\section{Return} +\subsection{Synopsis} +\begin{verbatim} +Return from gosub routine +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Return([return-value]) + Jumps to the last label on the stack, removing it. The return value, if +any, is saved in the channel variable GOSUB_RETVAL. + +\end{verbatim} + + +\section{Ringing} +\subsection{Synopsis} +\begin{verbatim} +Indicate ringing tone +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Ringing(): This application will request that the channel indicate a ringing +tone to the user. + +\end{verbatim} + + +\section{Rpt} +\subsection{Synopsis} +\begin{verbatim} +Radio Repeater/Remote Base Control System +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Rpt(nodename[|options]): Radio Remote Link or Remote Base Link Endpoint Process. + + Not specifying an option puts it in normal endpoint mode (where source + IP and nodename are verified). + + Options are as follows: + + X - Normal endpoint mode WITHOUT security check. Only specify + this if you have checked security already (like with an IAX2 + user/password or something). + + Rannounce-string[|timeout[|timeout-destination]] - Amateur Radio + Reverse Autopatch. Caller is put on hold, and announcement (as + specified by the 'announce-string') is played on radio system. + Users of radio system can access autopatch, dial specified + code, and pick up call. Announce-string is list of names of + recordings, or "PARKED" to substitute code for un-parking, + or "NODE" to substitute node number. + + P - Phone Control mode. This allows a regular phone user to have + full control and audio access to the radio system. For the + user to have DTMF control, the 'phone_functions' parameter + must be specified for the node in 'rpt.conf'. An additional + function (cop,6) must be listed so that PTT control is available. + + D - Dumb Phone Control mode. This allows a regular phone user to + have full control and audio access to the radio system. In this + mode, the PTT is activated for the entire length of the call. + For the user to have DTMF control (not generally recomended in + this mode), the 'dphone_functions' parameter must be specified + for the node in 'rpt.conf'. Otherwise no DTMF control will be + available to the phone user. + + +\end{verbatim} + + +\section{SayAlpha} +\subsection{Synopsis} +\begin{verbatim} +Say Alpha +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SayAlpha(string): This application will play the sounds that correspond to +the letters of the given string. + +\end{verbatim} + + +\section{SayDigits} +\subsection{Synopsis} +\begin{verbatim} +Say Digits +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SayDigits(digits): This application will play the sounds that correspond +to the digits of the given number. This will use the language that is currently +set for the channel. See the LANGUAGE function for more information on setting +the language for the channel. + +\end{verbatim} + + +\section{SayNumber} +\subsection{Synopsis} +\begin{verbatim} +Say Number +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SayNumber(digits[,gender]): This application will play the sounds that +correspond to the given number. Optionally, a gender may be specified. +This will use the language that is currently set for the channel. See the +LANGUAGE function for more information on setting the language for the channel. + +\end{verbatim} + + +\section{SayPhonetic} +\subsection{Synopsis} +\begin{verbatim} +Say Phonetic +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SayPhonetic(string): This application will play the sounds from the phonetic +alphabet that correspond to the letters in the given string. + +\end{verbatim} + + +\section{SayUnixTime} +\subsection{Synopsis} +\begin{verbatim} +Says a specified time in a custom format +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SayUnixTime([unixtime][|[timezone][|format]]) + unixtime: time, in seconds since Jan 1, 1970. May be negative. + defaults to now. + timezone: timezone, see /usr/share/zoneinfo for a list. + defaults to machine default. + format: a format the time is to be said in. See voicemail.conf. + defaults to "ABdY 'digits/at' IMp" + +\end{verbatim} + + +\section{SendDTMF} +\subsection{Synopsis} +\begin{verbatim} +Sends arbitrary DTMF digits +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SendDTMF(digits[|timeout_ms]): Sends DTMF digits on a channel. + Accepted digits: 0-9, *#abcd, w (.5s pause) + The application will either pass the assigned digits or terminate if it + encounters an error. + +\end{verbatim} + + +\section{SendImage} +\subsection{Synopsis} +\begin{verbatim} +Send an image file +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SendImage(filename): Sends an image on a channel. +If the channel supports image transport but the image send +fails, the channel will be hung up. Otherwise, the dialplan +continues execution. +This application sets the following channel variable upon completion: + SENDIMAGESTATUS The status is the result of the attempt as a text string, one of + OK | NOSUPPORT + +\end{verbatim} + + +\section{SendText} +\subsection{Synopsis} +\begin{verbatim} +Send a Text Message +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SendText(text[|options]): Sends text to current channel (callee). +Result of transmission will be stored in the SENDTEXTSTATUS +channel variable: + SUCCESS Transmission succeeded + FAILURE Transmission failed + UNSUPPORTED Text transmission not supported by channel + +At this moment, text is supposed to be 7 bit ASCII in most channels. + +\end{verbatim} + + +\section{SendURL} +\subsection{Synopsis} +\begin{verbatim} +Send a URL +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SendURL(URL[|option]): Requests client go to URL (IAX2) or sends the +URL to the client (other channels). +Result is returned in the SENDURLSTATUS channel variable: + SUCCESS URL successfully sent to client + FAILURE Failed to send URL + NOLOAD Client failed to load URL (wait enabled) + UNSUPPORTED Channel does not support URL transport + +If the option 'wait' is specified, execution will wait for an +acknowledgement that the URL has been loaded before continuing + +SendURL continues normally if the URL was sent correctly or if the channel +does not support HTML transport. Otherwise, the channel is hung up. + +\end{verbatim} + + +\section{Set} +\subsection{Synopsis} +\begin{verbatim} +Set channel variable(s) or function value(s) +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Set(name1=value1|name2=value2|..[|options]) +This function can be used to set the value of channel variables or dialplan +functions. It will accept up to 24 name/value pairs. When setting variables, +if the variable name is prefixed with _, the variable will be inherited into +channels created from the current channel. If the variable name is prefixed +with __, the variable will be inherited into channels created from the current +channel and all children channels. + Options: + g - Set variable globally instead of on the channel + (applies only to variables, not functions) + +\end{verbatim} + + +\section{SetAMAFlags} +\subsection{Synopsis} +\begin{verbatim} +Set the AMA Flags +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SetAMAFlags([flag]): This application will set the channel's AMA Flags for + billing purposes. + +\end{verbatim} + + +\section{SetCallerPres} +\subsection{Synopsis} +\begin{verbatim} +Set CallerID Presentation +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SetCallerPres(presentation): Set Caller*ID presentation on a call. + Valid presentations are: + + allowed_not_screened : Presentation Allowed, Not Screened + allowed_passed_screen : Presentation Allowed, Passed Screen + allowed_failed_screen : Presentation Allowed, Failed Screen + allowed : Presentation Allowed, Network Number + prohib_not_screened : Presentation Prohibited, Not Screened + prohib_passed_screen : Presentation Prohibited, Passed Screen + prohib_failed_screen : Presentation Prohibited, Failed Screen + prohib : Presentation Prohibited, Network Number + unavailable : Number Unavailable + + +\end{verbatim} + + +\section{SetMusicOnHold} +\subsection{Synopsis} +\begin{verbatim} +Set default Music On Hold class +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SetMusicOnHold(class): Sets the default class for music on hold for a given channel. When +music on hold is activated, this class will be used to select which +music is played. + +\end{verbatim} + + +\section{SIPAddHeader} +\subsection{Synopsis} +\begin{verbatim} +Add a SIP header to the outbound call +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SIPAddHeader(Header: Content) +Adds a header to a SIP call placed with DIAL. +Remember to user the X-header if you are adding non-standard SIP +headers, like "X-Asterisk-Accountcode:". Use this with care. +Adding the wrong headers may jeopardize the SIP dialog. +Always returns 0 + +\end{verbatim} + + +\section{SIPDtmfMode} +\subsection{Synopsis} +\begin{verbatim} +Change the dtmfmode for a SIP call +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SIPDtmfMode(inband|info|rfc2833): Changes the dtmfmode for a SIP call + +\end{verbatim} + + +\section{Skel} +\subsection{Synopsis} +\begin{verbatim} +Skeleton application. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This application is a template to build other applications from. + It shows you the basic structure to create your own Asterisk applications. + +\end{verbatim} + + +\section{SLAStation} +\subsection{Synopsis} +\begin{verbatim} +Shared Line Appearance Station +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SLAStation(station): +This application should be executed by an SLA station. The argument depends +on how the call was initiated. If the phone was just taken off hook, then +the argument "station" should be just the station name. If the call was +initiated by pressing a line key, then the station name should be preceded +by an underscore and the trunk name associated with that line button. +For example: "station1_line1". On exit, this application will set the variable SLASTATION_STATUS to +one of the following values: + FAILURE | CONGESTION | SUCCESS + +\end{verbatim} + + +\section{SLATrunk} +\subsection{Synopsis} +\begin{verbatim} +Shared Line Appearance Trunk +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SLATrunk(trunk): +This application should be executed by an SLA trunk on an inbound call. +The channel calling this application should correspond to the SLA trunk +with the name "trunk" that is being passed as an argument. + On exit, this application will set the variable SLATRUNK_STATUS to +one of the following values: + FAILURE | SUCCESS | UNANSWERED | RINGTIMEOUT + +\end{verbatim} + + +\section{SMS} +\subsection{Synopsis} +\begin{verbatim} +Communicates with SMS service centres and SMS capable analogue phones +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SMS(name|[a][s][t][p(d)][r][o]|addr|body): +SMS handles exchange of SMS data with a call to/from SMS capable +phone or SMS PSTN service center. Can send and/or receive SMS messages. +Works to ETSI ES 201 912; compatible with BT SMS PSTN service in UK +and Telecom Italia in Italy. +Typical usage is to use to handle calls from the SMS service centre CLI, +or to set up a call using 'outgoing' or manager interface to connect +service centre to SMS() +name is the name of the queue used in /var/spool/asterisk/sms +Arguments: + a: answer, i.e. send initial FSK packet. + s: act as service centre talking to a phone. + t: use protocol 2 (default used is protocol 1). + p(N): set the initial delay to N ms (default is 300). +addr and body are a deprecated format to send messages out. + s: set the Status Report Request (SRR) bit. + o: the body should be coded as octets not 7-bit symbols. +Messages are processed as per text file message queues. +smsq (a separate software) is a command to generate message +queues and send messages. +NOTE: the protocol has tight delay bounds. Please use short frames +and disable/keep short the jitter buffer on the ATA to make sure that +respones (ACK etc.) are received in time. + +\end{verbatim} + + +\section{SoftHangup} +\subsection{Synopsis} +\begin{verbatim} +Soft Hangup Application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + SoftHangup(Technology/resource|options) +Hangs up the requested channel. If there are no channels to hangup, +the application will report it. +- 'options' may contain the following letter: + 'a' : hang up all channels on a specified device instead of a single resource + +\end{verbatim} + + +\section{SpeechActivateGrammar} +\subsection{Synopsis} +\begin{verbatim} +Activate a Grammar +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechActivateGrammar(Grammar Name) +This activates the specified grammar to be recognized by the engine. A grammar tells the speech recognition engine what to recognize, +and how to portray it back to you in the dialplan. The grammar name is the only argument to this application. + +\end{verbatim} + + +\section{SpeechBackground} +\subsection{Synopsis} +\begin{verbatim} +Play a sound file and wait for speech to be recognized +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechBackground(Sound File|Timeout) +This application plays a sound file and waits for the person to speak. Once they start speaking playback of the file stops, and silence is heard. +Once they stop talking the processing sound is played to indicate the speech recognition engine is working. +Once results are available the application returns and results (score and text) are available using dialplan functions. +The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)} and ${SPEECH_SCORE(1)}. +The first argument is the sound file and the second is the timeout integer in seconds. Note the timeout will only start once the sound file has stopped playing. + +\end{verbatim} + + +\section{SpeechCreate} +\subsection{Synopsis} +\begin{verbatim} +Create a Speech Structure +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechCreate(engine name) +This application creates information to be used by all the other applications. It must be called before doing any speech recognition activities such as activating a grammar. +It takes the engine name to use as the argument, if not specified the default engine will be used. + +\end{verbatim} + + +\section{SpeechDeactivateGrammar} +\subsection{Synopsis} +\begin{verbatim} +Deactivate a Grammar +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechDeactivateGrammar(Grammar Name) +This deactivates the specified grammar so that it is no longer recognized. The only argument is the grammar name to deactivate. + +\end{verbatim} + + +\section{SpeechDestroy} +\subsection{Synopsis} +\begin{verbatim} +End speech recognition +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechDestroy() +This destroys the information used by all the other speech recognition applications. +If you call this application but end up wanting to recognize more speech, you must call SpeechCreate +again before calling any other application. It takes no arguments. + +\end{verbatim} + + +\section{SpeechLoadGrammar} +\subsection{Synopsis} +\begin{verbatim} +Load a Grammar +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechLoadGrammar(Grammar Name|Path) +Load a grammar only on the channel, not globally. +It takes the grammar name as first argument and path as second. + +\end{verbatim} + + +\section{SpeechProcessingSound} +\subsection{Synopsis} +\begin{verbatim} +Change background processing sound +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechProcessingSound(Sound File) +This changes the processing sound that SpeechBackground plays back when the speech recognition engine is processing and working to get results. +It takes the sound file as the only argument. + +\end{verbatim} + + +\section{SpeechStart} +\subsection{Synopsis} +\begin{verbatim} +Start recognizing voice in the audio stream +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechStart() +Tell the speech recognition engine that it should start trying to get results from audio being fed to it. This has no arguments. + +\end{verbatim} + + +\section{SpeechUnloadGrammar} +\subsection{Synopsis} +\begin{verbatim} +Unload a Grammar +\end{verbatim} +\subsection{Description} +\begin{verbatim} +SpeechUnloadGrammar(Grammar Name) +Unload a grammar. It takes the grammar name as the only argument. + +\end{verbatim} + + +\section{StackPop} +\subsection{Synopsis} +\begin{verbatim} +Remove one address from gosub stack +\end{verbatim} +\subsection{Description} +\begin{verbatim} +StackPop() + Removes last label on the stack, discarding it. + +\end{verbatim} + + +\section{StartMusicOnHold} +\subsection{Synopsis} +\begin{verbatim} +Play Music On Hold +\end{verbatim} +\subsection{Description} +\begin{verbatim} +StartMusicOnHold(class): Starts playing music on hold, uses default music class for channel. +Starts playing music specified by class. If omitted, the default +music source for the channel will be used. Always returns 0. + +\end{verbatim} + + +\section{StopMixMonitor} +\subsection{Synopsis} +\begin{verbatim} +Stop recording a call through MixMonitor +\end{verbatim} +\subsection{Description} +\begin{verbatim} + StopMixMonitor() + +Stops the audio recording that was started with a call to MixMonitor() +on the current channel. + +\end{verbatim} + + +\section{StopMonitor} +\subsection{Synopsis} +\begin{verbatim} +Stop monitoring a channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +StopMonitor +Stops monitoring a channel. Has no effect if the channel is not monitored + +\end{verbatim} + + +\section{StopMusicOnHold} +\subsection{Synopsis} +\begin{verbatim} +Stop Playing Music On Hold +\end{verbatim} +\subsection{Description} +\begin{verbatim} +StopMusicOnHold: Stops playing music on hold. + +\end{verbatim} + + +\section{StopPlayTones} +\subsection{Synopsis} +\begin{verbatim} +Stop playing a tone list +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Stop playing a tone list +\end{verbatim} + + +\section{System} +\subsection{Synopsis} +\begin{verbatim} +Execute a system command +\end{verbatim} +\subsection{Description} +\begin{verbatim} + System(command): Executes a command by using system(). If the command +fails, the console should report a fallthrough. +Result of execution is returned in the SYSTEMSTATUS channel variable: + FAILURE Could not execute the specified command + SUCCESS Specified command successfully executed + +\end{verbatim} + + +\section{TestClient} +\subsection{Synopsis} +\begin{verbatim} +Execute Interface Test Client +\end{verbatim} +\subsection{Description} +\begin{verbatim} +TestClient(testid): Executes test client with given testid. +Results stored in /var/log/asterisk/testreports/<testid>-client.txt +\end{verbatim} + + +\section{TestServer} +\subsection{Synopsis} +\begin{verbatim} +Execute Interface Test Server +\end{verbatim} +\subsection{Description} +\begin{verbatim} +TestServer(): Perform test server function and write call report. +Results stored in /var/log/asterisk/testreports/<testid>-server.txt +\end{verbatim} + + +\section{Transfer} +\subsection{Synopsis} +\begin{verbatim} +Transfer caller to remote extension +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Transfer([Tech/]dest[|options]): Requests the remote caller be transferred +to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only +an incoming call with the same channel technology will be transfered. +Note that for SIP, if you transfer before call is setup, a 302 redirect +SIP message will be returned to the caller. + +The result of the application will be reported in the TRANSFERSTATUS +channel variable: + SUCCESS Transfer succeeded + FAILURE Transfer failed + UNSUPPORTED Transfer unsupported by channel driver + +\end{verbatim} + + +\section{TryExec} +\subsection{Synopsis} +\begin{verbatim} +Executes dialplan application, always returning +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: TryExec(appname(arguments)) + Allows an arbitrary application to be invoked even when not +hardcoded into the dialplan. To invoke external applications +see the application System. Always returns to the dialplan. +The channel variable TRYSTATUS will be set to: + SUCCESS if the application returned zero + FAILED if the application returned non-zero + NOAPP if the application was not found or was not specified + +\end{verbatim} + + +\section{TrySystem} +\subsection{Synopsis} +\begin{verbatim} +Try executing a system command +\end{verbatim} +\subsection{Description} +\begin{verbatim} + TrySystem(command): Executes a command by using system(). +on any situation. +Result of execution is returned in the SYSTEMSTATUS channel variable: + FAILURE Could not execute the specified command + SUCCESS Specified command successfully executed + APPERROR Specified command successfully executed, but returned error code + +\end{verbatim} + + +\section{UnpauseMonitor} +\subsection{Synopsis} +\begin{verbatim} +Unpause monitoring of a channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +UnpauseMonitor +Unpauses monitoring of a channel on which monitoring had +previously been paused with PauseMonitor. + +\end{verbatim} + + +\section{UnpauseQueueMember} +\subsection{Synopsis} +\begin{verbatim} +Unpauses a queue member +\end{verbatim} +\subsection{Description} +\begin{verbatim} + UnpauseQueueMember([queuename]|interface[|options]): +Unpauses (resumes calls to) a queue member. +This is the counterpart to PauseQueueMember and operates exactly the +same way, except it unpauses instead of pausing the given interface. + This application sets the following channel variable upon completion: + UPQMSTATUS The status of the attempt to unpause a queue + member as a text string, one of + UNPAUSED | NOTFOUND +Example: UnpauseQueueMember(|SIP/3000) + +\end{verbatim} + + +\section{UserEvent} +\subsection{Synopsis} +\begin{verbatim} +Send an arbitrary event to the manager interface +\end{verbatim} +\subsection{Description} +\begin{verbatim} + UserEvent(eventname[|body]): Sends an arbitrary event to the manager +interface, with an optional body representing additional arguments. The +body may be specified as a | delimeted list of headers. Each additional +argument will be placed on a new line in the event. The format of the +event will be: + Event: UserEvent + UserEvent: <specified event name> + [body] +If no body is specified, only Event and UserEvent headers will be present. + +\end{verbatim} + + +\section{Verbose} +\subsection{Synopsis} +\begin{verbatim} +Send arbitrary text to verbose output +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Verbose([<level>|]<message>) + level must be an integer value. If not specified, defaults to 0. + +\end{verbatim} + + +\section{VMAuthenticate} +\subsection{Synopsis} +\begin{verbatim} +Authenticate with Voicemail passwords +\end{verbatim} +\subsection{Description} +\begin{verbatim} + VMAuthenticate([mailbox][@context][|options]): This application behaves the +same way as the Authenticate application, but the passwords are taken from +voicemail.conf. + If the mailbox is specified, only that mailbox's password will be considered +valid. If the mailbox is not specified, the channel variable AUTH_MAILBOX will +be set with the authenticated mailbox. + + Options: + s - Skip playing the initial prompts. + +\end{verbatim} + + +\section{VoiceMail} +\subsection{Synopsis} +\begin{verbatim} +Leave a Voicemail message +\end{verbatim} +\subsection{Description} +\begin{verbatim} + VoiceMail(mailbox[@context][&mailbox[@context]][...][|options]): This +application allows the calling party to leave a message for the specified +list of mailboxes. When multiple mailboxes are specified, the greeting will +be taken from the first mailbox specified. Dialplan execution will stop if the +specified mailbox does not exist. + The Voicemail application will exit if any of the following DTMF digits are +received: + 0 - Jump to the 'o' extension in the current dialplan context. + * - Jump to the 'a' extension in the current dialplan context. + This application will set the following channel variable upon completion: + VMSTATUS - This indicates the status of the execution of the VoiceMail + application. The possible values are: + SUCCESS | USEREXIT | FAILED + + Options: + b - Play the 'busy' greeting to the calling party. + g(#) - Use the specified amount of gain when recording the voicemail + message. The units are whole-number decibels (dB). + s - Skip the playback of instructions for leaving a message to the + calling party. + u - Play the 'unavailable greeting. + +\end{verbatim} + + +\section{VoiceMailMain} +\subsection{Synopsis} +\begin{verbatim} +Check Voicemail messages +\end{verbatim} +\subsection{Description} +\begin{verbatim} + VoiceMailMain([mailbox][@context][|options]): This application allows the +calling party to check voicemail messages. A specific mailbox, and optional +corresponding context, may be specified. If a mailbox is not provided, the +calling party will be prompted to enter one. If a context is not specified, +the 'default' context will be used. + + Options: + p - Consider the mailbox parameter as a prefix to the mailbox that + is entered by the caller. + g(#) - Use the specified amount of gain when recording a voicemail + message. The units are whole-number decibels (dB). + s - Skip checking the passcode for the mailbox. + a(#) - Skip folder prompt and go directly to folder specified. + Defaults to INBOX + +\end{verbatim} + + +\section{Wait} +\subsection{Synopsis} +\begin{verbatim} +Waits for some time +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Wait(seconds): This application waits for a specified number of seconds. +Then, dialplan execution will continue at the next priority. + Note that the seconds can be passed with fractions of a second. For example, +'1.5' will ask the application to wait for 1.5 seconds. + +\end{verbatim} + + +\section{WaitExten} +\subsection{Synopsis} +\begin{verbatim} +Waits for an extension to be entered +\end{verbatim} +\subsection{Description} +\begin{verbatim} + WaitExten([seconds][|options]): This application waits for the user to enter +a new extension for a specified number of seconds. + Note that the seconds can be passed with fractions of a second. For example, +'1.5' will ask the application to wait for 1.5 seconds. + Options: + m[(x)] - Provide music on hold to the caller while waiting for an extension. + Optionally, specify the class for music on hold within parenthesis. + +\end{verbatim} + + +\section{WaitForRing} +\subsection{Synopsis} +\begin{verbatim} +Wait for Ring Application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + WaitForRing(timeout) +Returns 0 after waiting at least timeout seconds. and +only after the next ring has completed. Returns 0 on +success or -1 on hangup + +\end{verbatim} + + +\section{WaitForSilence} +\subsection{Synopsis} +\begin{verbatim} +Waits for a specified amount of silence +\end{verbatim} +\subsection{Description} +\begin{verbatim} + WaitForSilence(silencerequired[|iterations][|timeout]) +Wait for Silence: Waits for up to 'silencerequired' +milliseconds of silence, 'iterations' times or once if omitted. +An optional timeout specified the number of seconds to return +after, even if we do not receive the specified amount of silence. +Use 'timeout' with caution, as it may defeat the purpose of this +application, which is to wait indefinitely until silence is detected +on the line. This is particularly useful for reverse-911-type +call broadcast applications where you need to wait for an answering +machine to complete its spiel before playing a message. +The timeout parameter is specified only to avoid an infinite loop in +cases where silence is never achieved. Typically you will want to +include two or more calls to WaitForSilence when dealing with an answering +machine; first waiting for the spiel to finish, then waiting for the beep, etc. + +Examples: + - WaitForSilence(500|2) will wait for 1/2 second of silence, twice + - WaitForSilence(1000) will wait for 1 second of silence, once + - WaitForSilence(300|3|10) will wait for 300ms silence, 3 times, + and returns after 10 sec, even if silence is not detected + +Sets the channel variable WAITSTATUS with to one of these values: +SILENCE - if exited with silence detected +TIMEOUT - if exited without silence detected after timeout + +\end{verbatim} + + +\section{WaitMusicOnHold} +\subsection{Synopsis} +\begin{verbatim} +Wait, playing Music On Hold +\end{verbatim} +\subsection{Description} +\begin{verbatim} +WaitMusicOnHold(delay): Plays hold music specified number of seconds. Returns 0 when +done, or -1 on hangup. If no hold music is available, the delay will +still occur with no sound. + +\end{verbatim} + + +\section{While} +\subsection{Synopsis} +\begin{verbatim} +Start a while loop +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Usage: While(<expr>) +Start a While Loop. Execution will return to this point when +EndWhile is called until expr is no longer true. + +\end{verbatim} + + +\section{Zapateller} +\subsection{Synopsis} +\begin{verbatim} +Block telemarketers with SIT +\end{verbatim} +\subsection{Description} +\begin{verbatim} + Zapateller(options): Generates special information tone to block +telemarketers from calling you. Options is a pipe-delimited list of +options. The following options are available: +'answer' causes the line to be answered before playing the tone, +'nocallerid' causes Zapateller to only play the tone if there +is no callerid information available. Options should be separated by | +characters + +\end{verbatim} + + +\section{ZapBarge} +\subsection{Synopsis} +\begin{verbatim} +Barge in (monitor) Zap channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ZapBarge([channel]): Barges in on a specified zap +channel or prompts if one is not specified. Returns +-1 when caller user hangs up and is independent of the +state of the channel being monitored. +\end{verbatim} + + +\section{ZapRAS} +\subsection{Synopsis} +\begin{verbatim} +Executes Zaptel ISDN RAS application +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ZapRAS(args): Executes a RAS server using pppd on the given channel. +The channel must be a clear channel (i.e. PRI source) and a Zaptel +channel to be able to use this function (No modem emulation is included). +Your pppd must be patched to be zaptel aware. Arguments should be +separated by | characters. + +\end{verbatim} + + +\section{ZapScan} +\subsection{Synopsis} +\begin{verbatim} +Scan Zap channels to monitor calls +\end{verbatim} +\subsection{Description} +\begin{verbatim} + ZapScan([group]) allows a call center manager to monitor Zap channels in +a convenient way. Use '#' to select the next channel and use '*' to exit +Limit scanning to a channel GROUP by setting the option group argument. + +\end{verbatim} + + diff --git a/doc/tex/ast_cli_commands.tex b/doc/tex/ast_cli_commands.tex new file mode 100644 index 000000000..e7e58b4e4 --- /dev/null +++ b/doc/tex/ast_cli_commands.tex @@ -0,0 +1,3505 @@ +% This file is automatically generated by the "core dump clidocs" CLI command. Any manual edits will be lost. +\section{!} +\subsection{Summary} +\begin{verbatim} +Execute a shell command +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: !<command> + Executes a given shell command + +\end{verbatim} + + +\section{abort halt} +\subsection{Summary} +\begin{verbatim} +Cancel a running halt +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: abort shutdown + Causes Asterisk to abort an executing shutdown or restart, and resume normal + call operations. + +\end{verbatim} + + +\section{ael debug contexts} +\subsection{Summary} +\begin{verbatim} +Enable AEL contexts debug (does nothing) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ael debug macros} +\subsection{Summary} +\begin{verbatim} +Enable AEL macros debug (does nothing) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ael debug read} +\subsection{Summary} +\begin{verbatim} +Enable AEL read debug (does nothing) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ael debug tokens} +\subsection{Summary} +\begin{verbatim} +Enable AEL tokens debug (does nothing) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ael nodebug} +\subsection{Summary} +\begin{verbatim} +Disable AEL debug messages +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ael reload} +\subsection{Summary} +\begin{verbatim} +Reload AEL configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{agent logoff} +\subsection{Summary} +\begin{verbatim} +Sets an agent offline +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agent logoff <channel> [soft] + Sets an agent as no longer logged in. + If 'soft' is specified, do not hangup existing calls. + +\end{verbatim} + + +\section{agent show} +\subsection{Summary} +\begin{verbatim} +Show status of agents +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agent show + Provides summary information on agents. + +\end{verbatim} + + +\section{agent show online} +\subsection{Summary} +\begin{verbatim} +Show all online agents +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agent show online + Provides a list of all online agents. + +\end{verbatim} + + +\section{agi debug} +\subsection{Summary} +\begin{verbatim} +Enable AGI debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agi debug + Enables dumping of AGI transactions for debugging purposes + +\end{verbatim} + + +\section{agi debug off} +\subsection{Summary} +\begin{verbatim} +Disable AGI debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agi debug off + Disables dumping of AGI transactions for debugging purposes + +\end{verbatim} + + +\section{agi dump commanddocs} +\subsection{Summary} +\begin{verbatim} +Dump agi command documentation in LaTeX format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agi dump commanddocs [command] + Dump manager action documentation to /tmp/ast_agi_commands.tex. + +\end{verbatim} + + +\section{agi dumphtml} +\subsection{Summary} +\begin{verbatim} +Dumps a list of agi commands in html format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agi dumphtml <filename> + Dumps the agi command list in html format to given filename + +\end{verbatim} + + +\section{agi show} +\subsection{Summary} +\begin{verbatim} +List AGI commands or specific help +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: agi show [topic] + When called with a topic as an argument, displays usage + information on the given command. If called without a + topic, it provides a list of AGI commands. + +\end{verbatim} + + +\section{cdr status} +\subsection{Summary} +\begin{verbatim} +Display the CDR status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: cdr status + Displays the Call Detail Record engine system status. + +\end{verbatim} + + +\section{console active} +\subsection{Summary} +\begin{verbatim} +Sets/displays active console +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console active [device] + If used without a parameter, displays which device is the current +console. If a device is specified, the console sound device is changed to +the device specified. + +\end{verbatim} + + +\section{console answer} +\subsection{Summary} +\begin{verbatim} +Answer an incoming console call +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console answer + Answers an incoming call on the console (OSS) channel. + +\end{verbatim} + + +\section{console autoanswer [on|off]} +\subsection{Summary} +\begin{verbatim} +Sets/displays autoanswer +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console autoanswer [on|off] + Enables or disables autoanswer feature. If used without + argument, displays the current on/off status of autoanswer. + The default value of autoanswer is in 'oss.conf'. + +\end{verbatim} + + +\section{console boost} +\subsection{Summary} +\begin{verbatim} +Sets/displays mic boost in dB +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{console dial} +\subsection{Summary} +\begin{verbatim} +Dial an extension on the console +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console dial [extension[@context]] + Dials a given extension (and context if specified) + +\end{verbatim} + + +\section{console flash} +\subsection{Summary} +\begin{verbatim} +Flash a call on the console +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console flash + Flashes the call currently placed on the console. + +\end{verbatim} + + +\section{console hangup} +\subsection{Summary} +\begin{verbatim} +Hangup a call on the console +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console hangup + Hangs up any call currently placed on the console. + +\end{verbatim} + + +\section{console {mute|unmute}} +\subsection{Summary} +\begin{verbatim} +Disable/Enable mic input +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console {mute|unmute} + Mute/unmute the microphone. + +\end{verbatim} + + +\section{console send text} +\subsection{Summary} +\begin{verbatim} +Send text to the remote device +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console send text <message> + Sends a text message for display on the remote terminal. + +\end{verbatim} + + +\section{console transfer} +\subsection{Summary} +\begin{verbatim} +Transfer a call to a different extension +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: console transfer <extension>[@context] + Transfers the currently connected call to the given extension (and +context if specified) + +\end{verbatim} + + +\section{core clear profile} +\subsection{Summary} +\begin{verbatim} +Clear profiling info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{core dump appdocs} +\subsection{Summary} +\begin{verbatim} +Dump application documentation in LaTeX format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core dump appdocs [application] + Dump Application documentation to /tmp/ast_appdocs.tex. + +\end{verbatim} + + +\section{core dump clidocs} +\subsection{Summary} +\begin{verbatim} +Dump CLI command documentation in LaTeX format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core dump clidocs + Dump CLI command documentation to /tmp/ast_cli_commands.tex. + +\end{verbatim} + + +\section{core dump funcdocs} +\subsection{Summary} +\begin{verbatim} +Dump function documentation in LaTeX format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core dump funcdocs [function] + Dump Application documentation to /tmp/ast_funcdocs.tex. + +\end{verbatim} + + +\section{core set debug channel} +\subsection{Summary} +\begin{verbatim} +Enable/disable debugging on a channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core set debug channel <all|channel> [off] + Enables/disables debugging on all or on a specific channel. + +\end{verbatim} + + +\section{core set {debug|verbose} [off|atleast]} +\subsection{Summary} +\begin{verbatim} +Set level of debug/verbose chattiness +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core set {debug|verbose} [atleast] <level> + core set {debug|verbose} off + Sets level of debug or verbose messages to be displayed. + 0 or off means no messages should be displayed. + Equivalent to -d[d[...]] or -v[v[v...]] on startup + +\end{verbatim} + + +\section{core set global} +\subsection{Summary} +\begin{verbatim} +Set global dialplan variable +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core set global <name> <value> + Set global dialplan variable <name> to <value> + +\end{verbatim} + + +\section{core show applications} +\subsection{Summary} +\begin{verbatim} +Shows registered dialplan applications +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show applications [{like|describing} <text>] + List applications which are currently available. + If 'like', <text> will be a substring of the app name + If 'describing', <text> will be a substring of the description + +\end{verbatim} + + +\section{core show application} +\subsection{Summary} +\begin{verbatim} +Describe a specific dialplan application +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show application <application> [<application> [<application> [...]]] + Describes a particular application. + +\end{verbatim} + + +\section{core show channels [concise|verbose|count]} +\subsection{Summary} +\begin{verbatim} +Display information on channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show channels [concise|verbose|count] + Lists currently defined channels and some information about them. If + 'concise' is specified, the format is abridged and in a more easily + machine parsable format. If 'verbose' is specified, the output includes + more and longer fields. If 'count' is specified only the channel and call + count is output. + +\end{verbatim} + + +\section{core show channel} +\subsection{Summary} +\begin{verbatim} +Display information on a specific channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show channel <channel> + Shows lots of information about the specified channel. + +\end{verbatim} + + +\section{core show channeltypes} +\subsection{Summary} +\begin{verbatim} +List available channel types +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show channeltypes + Lists available channel types registered in your Asterisk server. + +\end{verbatim} + + +\section{core show channeltype} +\subsection{Summary} +\begin{verbatim} +Give more details on that channel type +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show channeltype <name> + Show details about the specified channel type, <name>. + +\end{verbatim} + + +\section{core show codecs} +\subsection{Summary} +\begin{verbatim} +Displays a list of codecs +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show codecs [audio|video|image] + Displays codec mapping + +\end{verbatim} + + +\section{core show codecs audio} +\subsection{Summary} +\begin{verbatim} +Displays a list of audio codecs +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show codecs [audio|video|image] + Displays codec mapping + +\end{verbatim} + + +\section{core show codecs image} +\subsection{Summary} +\begin{verbatim} +Displays a list of image codecs +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show codecs [audio|video|image] + Displays codec mapping + +\end{verbatim} + + +\section{core show codecs video} +\subsection{Summary} +\begin{verbatim} +Displays a list of video codecs +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show codecs [audio|video|image] + Displays codec mapping + +\end{verbatim} + + +\section{core show codec} +\subsection{Summary} +\begin{verbatim} +Shows a specific codec +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show codec <number> + Displays codec mapping + +\end{verbatim} + + +\section{core show config mappings} +\subsection{Summary} +\begin{verbatim} +Display config mappings (file names to config engines) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show config mappings + Shows the filenames to config engines. + +\end{verbatim} + + +\section{core show file formats} +\subsection{Summary} +\begin{verbatim} +Displays file formats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show file formats + Displays currently registered file formats (if any) + +\end{verbatim} + + +\section{core show file version} +\subsection{Summary} +\begin{verbatim} +List versions of files used to build Asterisk +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show file version [like <pattern>] + Lists the revision numbers of the files used to build this copy of Asterisk. + Optional regular expression pattern is used to filter the file list. + +\end{verbatim} + + +\section{core show functions} +\subsection{Summary} +\begin{verbatim} +Shows registered dialplan functions +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show functions [like <text>] + List builtin functions, optionally only those matching a given string + +\end{verbatim} + + +\section{core show function} +\subsection{Summary} +\begin{verbatim} +Describe a specific dialplan function +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show function <function> + Describe a particular dialplan function. + +\end{verbatim} + + +\section{core show globals} +\subsection{Summary} +\begin{verbatim} +Show global dialplan variables +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show globals + List current global dialplan variables and their values + +\end{verbatim} + + +\section{core show hints} +\subsection{Summary} +\begin{verbatim} +Show dialplan hints +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show hints + List registered hints + +\end{verbatim} + + +\section{core show image formats} +\subsection{Summary} +\begin{verbatim} +Displays image formats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show image formats + displays currently registered image formats (if any) + +\end{verbatim} + + +\section{core show license} +\subsection{Summary} +\begin{verbatim} +Show the license(s) for this copy of Asterisk +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show license + Shows the license(s) for this copy of Asterisk. + +\end{verbatim} + + +\section{core show profile} +\subsection{Summary} +\begin{verbatim} +Display profiling info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{core show settings} +\subsection{Summary} +\begin{verbatim} +Show some core settings +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{core show switches} +\subsection{Summary} +\begin{verbatim} +Show alternative switches +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show switches + List registered switches + +\end{verbatim} + + +\section{core show sysinfo} +\subsection{Summary} +\begin{verbatim} +Show System Information +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show sysinfo + List current system information. + +\end{verbatim} + + +\section{core show threads} +\subsection{Summary} +\begin{verbatim} +Show running threads +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show threads + List threads currently active in the system. + +\end{verbatim} + + +\section{core show translation} +\subsection{Summary} +\begin{verbatim} +Display translation matrix +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show translation [recalc] [<recalc seconds>] + Displays known codec translators and the cost associated +with each conversion. If the argument 'recalc' is supplied along +with optional number of seconds to test a new test will be performed +as the chart is being displayed. + +\end{verbatim} + + +\section{core show uptime [seconds]} +\subsection{Summary} +\begin{verbatim} +Show uptime information +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show uptime [seconds] + Shows Asterisk uptime information. + The seconds word returns the uptime in seconds only. + +\end{verbatim} + + +\section{core show version} +\subsection{Summary} +\begin{verbatim} +Display version info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show version + Shows Asterisk version information. + +\end{verbatim} + + +\section{core show warranty} +\subsection{Summary} +\begin{verbatim} +Show the warranty (if any) for this copy of Asterisk +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show warranty + Shows the warranty (if any) for this copy of Asterisk. + +\end{verbatim} + + +\section{database del} +\subsection{Summary} +\begin{verbatim} +Removes database key/value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database del <family> <key> + Deletes an entry in the Asterisk database for a given +family and key. + +\end{verbatim} + + +\section{database deltree} +\subsection{Summary} +\begin{verbatim} +Removes database keytree/values +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database deltree <family> [keytree] + Deletes a family or specific keytree within a family +in the Asterisk database. + +\end{verbatim} + + +\section{database get} +\subsection{Summary} +\begin{verbatim} +Gets database value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database get <family> <key> + Retrieves an entry in the Asterisk database for a given +family and key. + +\end{verbatim} + + +\section{database put} +\subsection{Summary} +\begin{verbatim} +Adds/updates database value +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database put <family> <key> <value> + Adds or updates an entry in the Asterisk database for +a given family, key, and value. + +\end{verbatim} + + +\section{database show} +\subsection{Summary} +\begin{verbatim} +Shows database contents +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database show [family [keytree]] + Shows Asterisk database contents, optionally restricted +to a given family, or family and keytree. + +\end{verbatim} + + +\section{database showkey} +\subsection{Summary} +\begin{verbatim} +Shows database contents +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: database showkey <keytree> + Shows Asterisk database contents, restricted to a given key. + +\end{verbatim} + + +\section{dialplan add extension} +\subsection{Summary} +\begin{verbatim} +Add new extension into context +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan add extension <exten>,<priority>,<app>,<app-data> + into <context> [replace] + + This command will add new extension into <context>. If there is an + existence of extension with the same priority and last 'replace' + arguments is given here we simply replace this extension. + +Example: dialplan add extension 6123,1,Dial,IAX/216.207.245.56/6123 into local + Now, you can dial 6123 and talk to Markster :) + +\end{verbatim} + + +\section{dialplan add ignorepat} +\subsection{Summary} +\begin{verbatim} +Add new ignore pattern +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan add ignorepat <pattern> into <context> + This command adds a new ignore pattern into context <context> + +Example: dialplan add ignorepat _3XX into local + +\end{verbatim} + + +\section{dialplan add include} +\subsection{Summary} +\begin{verbatim} +Include context in other context +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan add include <context> into <context> + Include a context in another context. + +\end{verbatim} + + +\section{dialplan reload} +\subsection{Summary} +\begin{verbatim} +Reload extensions and *only* extensions +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan reload + reload extensions.conf without reloading any other modules + This command does not delete global variables unless + clearglobalvars is set to yes in extensions.conf + +\end{verbatim} + + +\section{dialplan remove extension} +\subsection{Summary} +\begin{verbatim} +Remove a specified extension +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan remove extension exten@context [priority] + Remove an extension from a given context. If a priority + is given, only that specific priority from the given extension + will be removed. + +\end{verbatim} + + +\section{dialplan remove ignorepat} +\subsection{Summary} +\begin{verbatim} +Remove ignore pattern from context +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan remove ignorepat <pattern> from <context> + This command removes an ignore pattern from context <context> + +Example: dialplan remove ignorepat _3XX from local + +\end{verbatim} + + +\section{dialplan remove include} +\subsection{Summary} +\begin{verbatim} +Remove a specified include from context +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan remove include <context> from <context> + Remove an included context from another context. + +\end{verbatim} + + +\section{dialplan save} +\subsection{Summary} +\begin{verbatim} +Save dialplan +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dialplan save [/path/to/extension/file] + Save dialplan created by pbx_config module. + +Example: dialplan save (/etc/asterisk/extensions.conf) + dialplan save /home/markster (/home/markster/extensions.conf) + +\end{verbatim} + + +\section{dialplan show} +\subsection{Summary} +\begin{verbatim} +Show dialplan +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core show dialplan [exten@][context] + Show dialplan + +\end{verbatim} + + +\section{dnsmgr reload} +\subsection{Summary} +\begin{verbatim} +Reloads the DNS manager configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dnsmgr reload + Reloads the DNS manager configuration. + +\end{verbatim} + + +\section{dnsmgr status} +\subsection{Summary} +\begin{verbatim} +Display the DNS manager status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dnsmgr status + Displays the DNS manager status. + +\end{verbatim} + + +\section{dundi debug} +\subsection{Summary} +\begin{verbatim} +Enable DUNDi debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi debug + Enables dumping of DUNDi packets for debugging purposes + +\end{verbatim} + + +\section{dundi flush} +\subsection{Summary} +\begin{verbatim} +Flush DUNDi cache +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi flush [stats] + Flushes DUNDi answer cache, used primarily for debug. If +'stats' is present, clears timer statistics instead of normal +operation. + +\end{verbatim} + + +\section{dundi lookup} +\subsection{Summary} +\begin{verbatim} +Lookup a number in DUNDi +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi lookup <number>[@context] [bypass] + Lookup the given number within the given DUNDi context +(or e164 if none is specified). Bypasses cache if 'bypass' +keyword is specified. + +\end{verbatim} + + +\section{dundi no debug} +\subsection{Summary} +\begin{verbatim} +Disable DUNDi debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi no debug + Disables dumping of DUNDi packets for debugging purposes + +\end{verbatim} + + +\section{dundi no store history} +\subsection{Summary} +\begin{verbatim} +Disable DUNDi historic records +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi no store history + Disables storing of DUNDi requests and times for debugging +purposes + +\end{verbatim} + + +\section{dundi precache} +\subsection{Summary} +\begin{verbatim} +Precache a number in DUNDi +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi precache <number>[@context] + Lookup the given number within the given DUNDi context +(or e164 if none is specified) and precaches the results to any +upstream DUNDi push servers. + +\end{verbatim} + + +\section{dundi query} +\subsection{Summary} +\begin{verbatim} +Query a DUNDi EID +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi query <entity>[@context] + Attempts to retrieve contact information for a specific +DUNDi entity identifier (EID) within a given DUNDi context (or +e164 if none is specified). + +\end{verbatim} + + +\section{dundi show entityid} +\subsection{Summary} +\begin{verbatim} +Display Global Entity ID +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show entityid + Displays the global entityid for this host. + +\end{verbatim} + + +\section{dundi show mappings} +\subsection{Summary} +\begin{verbatim} +Show DUNDi mappings +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show mappings + Lists all known DUNDi mappings. + +\end{verbatim} + + +\section{dundi show peers} +\subsection{Summary} +\begin{verbatim} +Show defined DUNDi peers +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show peers + Lists all known DUNDi peers. + +\end{verbatim} + + +\section{dundi show peer} +\subsection{Summary} +\begin{verbatim} +Show info on a specific DUNDi peer +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show peer [peer] + Provide a detailed description of a specifid DUNDi peer. + +\end{verbatim} + + +\section{dundi show precache} +\subsection{Summary} +\begin{verbatim} +Show DUNDi precache +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show precache + Lists all known DUNDi scheduled precache updates. + +\end{verbatim} + + +\section{dundi show requests} +\subsection{Summary} +\begin{verbatim} +Show DUNDi requests +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show requests + Lists all known pending DUNDi requests. + +\end{verbatim} + + +\section{dundi show trans} +\subsection{Summary} +\begin{verbatim} +Show active DUNDi transactions +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi show trans + Lists all known DUNDi transactions. + +\end{verbatim} + + +\section{dundi store history} +\subsection{Summary} +\begin{verbatim} +Enable DUNDi historic records +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: dundi store history + Enables storing of DUNDi requests and times for debugging +purposes + +\end{verbatim} + + +\section{feature show} +\subsection{Summary} +\begin{verbatim} +Lists configured features +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: feature list + Lists currently configured features. + +\end{verbatim} + + +\section{file convert} +\subsection{Summary} +\begin{verbatim} +Convert audio file +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: file convert <file_in> <file_out> + Convert from file_in to file_out. If an absolute path is not given, the +default Asterisk sounds directory will be used. + +Example: + file convert tt-weasels.gsm tt-weasels.ulaw + +\end{verbatim} + + +\section{funcdevstate list} +\subsection{Summary} +\begin{verbatim} +List currently known custom device states +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: funcdevstate list + List all custom device states that have been set by using + the DEVSTATE dialplan function. + +\end{verbatim} + + +\section{group show channels} +\subsection{Summary} +\begin{verbatim} +Display active channels with group(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: group show channels [pattern] + Lists all currently active channels with channel group(s) specified. + Optional regular expression pattern is matched to group names for each + channel. + +\end{verbatim} + + +\section{gtalk reload} +\subsection{Summary} +\begin{verbatim} +Enable Jabber debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: gtalk reload + Reload gtalk channel driver. + +\end{verbatim} + + +\section{gtalk show channels} +\subsection{Summary} +\begin{verbatim} +Show GoogleTalk Channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: gtalk show channels + Shows current state of the Gtalk channels. + +\end{verbatim} + + +\section{h323 cycle gk} +\subsection{Summary} +\begin{verbatim} +Manually re-register with the Gatekeper +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 gk cycle + Manually re-register with the Gatekeper (Currently Disabled) + +\end{verbatim} + + +\section{h323 hangup} +\subsection{Summary} +\begin{verbatim} +Manually try to hang up a call +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 hangup <token> + Manually try to hang up call identified by <token> + +\end{verbatim} + + +\section{h323 reload} +\subsection{Summary} +\begin{verbatim} +Reload H.323 configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 reload + Reloads H.323 configuration from h323.conf + +\end{verbatim} + + +\section{h323 set debug} +\subsection{Summary} +\begin{verbatim} +Enable H.323 debug +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 debug + Enables H.323 debug output + +\end{verbatim} + + +\section{h323 set debug off} +\subsection{Summary} +\begin{verbatim} +Disable H.323 debug +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 no debug + Disables H.323 debug output + +\end{verbatim} + + +\section{h323 set trace} +\subsection{Summary} +\begin{verbatim} +Enable H.323 Stack Tracing +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 trace <level num> + Enables H.323 stack tracing for debugging purposes + +\end{verbatim} + + +\section{h323 set trace off} +\subsection{Summary} +\begin{verbatim} +Disable H.323 Stack Tracing +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 no trace + Disables H.323 stack tracing for debugging purposes + +\end{verbatim} + + +\section{h323 show tokens} +\subsection{Summary} +\begin{verbatim} +Show all active call tokens +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: h323 show tokens + Print out all active call tokens + +\end{verbatim} + + +\section{help} +\subsection{Summary} +\begin{verbatim} +Display help list, or specific help on a command +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: help [topic] + When called with a topic as an argument, displays usage + information on the given command. If called without a + topic, it provides a list of commands. + +\end{verbatim} + + +\section{http show status} +\subsection{Summary} +\begin{verbatim} +Display HTTP server status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: http show status + Lists status of internal HTTP engine + +\end{verbatim} + + +\section{iax2 provision} +\subsection{Summary} +\begin{verbatim} +Provision an IAX device +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 provision <host> <template> [forced] + Provisions the given peer or IP address using a template + matching either 'template' or '*' if the template is not + found. If 'forced' is specified, even empty provisioning + fields will be provisioned as empty fields. + +\end{verbatim} + + +\section{iax2 prune realtime} +\subsection{Summary} +\begin{verbatim} +Prune a cached realtime lookup +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 prune realtime [<peername>|all] + Prunes object(s) from the cache + +\end{verbatim} + + +\section{iax2 reload} +\subsection{Summary} +\begin{verbatim} +Reload IAX configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 reload + Reloads IAX configuration from iax.conf + +\end{verbatim} + + +\section{iax2 set debug} +\subsection{Summary} +\begin{verbatim} +Enable IAX debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug + Enables dumping of IAX packets for debugging purposes + +\end{verbatim} + + +\section{iax2 set debug jb} +\subsection{Summary} +\begin{verbatim} +Enable IAX jitterbuffer debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug jb + Enables jitterbuffer debugging information + +\end{verbatim} + + +\section{iax2 set debug jb off} +\subsection{Summary} +\begin{verbatim} +Disable IAX jitterbuffer debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug jb off + Disables jitterbuffer debugging information + +\end{verbatim} + + +\section{iax2 set debug off} +\subsection{Summary} +\begin{verbatim} +Disable IAX debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug off + Disables dumping of IAX packets for debugging purposes + +\end{verbatim} + + +\section{iax2 set debug trunk} +\subsection{Summary} +\begin{verbatim} +Enable IAX trunk debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug trunk + Requests current status of IAX trunking + +\end{verbatim} + + +\section{iax2 set debug trunk off} +\subsection{Summary} +\begin{verbatim} +Disable IAX trunk debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set debug trunk off + Requests current status of IAX trunking + +\end{verbatim} + + +\section{iax2 set mtu} +\subsection{Summary} +\begin{verbatim} +Set the IAX systemwide trunking MTU +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 set mtu <value> + Set the system-wide IAX IP mtu to <value> bytes net or zero to disable. + Disabling means that the operating system must handle fragmentation of UDP packets + when the IAX2 trunk packet exceeds the UDP payload size. + This is substantially below the IP mtu. Try 1240 on ethernets. + Must be 172 or greater for G.711 samples. + +\end{verbatim} + + +\section{iax2 show cache} +\subsection{Summary} +\begin{verbatim} +Display IAX cached dialplan +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show cache + Display currently cached IAX Dialplan results. + +\end{verbatim} + + +\section{iax2 show channels} +\subsection{Summary} +\begin{verbatim} +List active IAX channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show channels + Lists all currently active IAX channels. + +\end{verbatim} + + +\section{iax2 show firmware} +\subsection{Summary} +\begin{verbatim} +List available IAX firmwares +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show firmware + Lists all known IAX firmware images. + +\end{verbatim} + + +\section{iax2 show netstats} +\subsection{Summary} +\begin{verbatim} +List active IAX channel netstats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show netstats + Lists network status for all currently active IAX channels. + +\end{verbatim} + + +\section{iax2 show peers} +\subsection{Summary} +\begin{verbatim} +List defined IAX peers +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show peers [registered] [like <pattern>] + Lists all known IAX2 peers. + Optional 'registered' argument lists only peers with known addresses. + Optional regular expression pattern is used to filter the peer list. + +\end{verbatim} + + +\section{iax2 show peer} +\subsection{Summary} +\begin{verbatim} +Show details on specific IAX peer +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show peer <name> + Display details on specific IAX peer + +\end{verbatim} + + +\section{iax2 show provisioning} +\subsection{Summary} +\begin{verbatim} +Display iax provisioning +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax list provisioning [template] + Lists all known IAX provisioning templates or a + specific one if specified. + +\end{verbatim} + + +\section{iax2 show registry} +\subsection{Summary} +\begin{verbatim} +Display IAX registration status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show registry + Lists all registration requests and status. + +\end{verbatim} + + +\section{iax2 show stats} +\subsection{Summary} +\begin{verbatim} +Display IAX statistics +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show stats + Display statistics on IAX channel driver. + +\end{verbatim} + + +\section{iax2 show threads} +\subsection{Summary} +\begin{verbatim} +Display IAX helper thread info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show threads + Lists status of IAX helper threads + +\end{verbatim} + + +\section{iax2 show users} +\subsection{Summary} +\begin{verbatim} +List defined IAX users +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 show users [like <pattern>] + Lists all known IAX2 users. + Optional regular expression pattern is used to filter the user list. + +\end{verbatim} + + +\section{iax2 test losspct} +\subsection{Summary} +\begin{verbatim} +Set IAX2 incoming frame loss percentage +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 test losspct <percentage> + For testing, throws away <percentage> percent of incoming packets + +\end{verbatim} + + +\section{iax2 unregister} +\subsection{Summary} +\begin{verbatim} +Unregister (force expiration) an IAX2 peer from the registry +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: iax2 unregister <peername> + Unregister (force expiration) an IAX2 peer from the registry. + +\end{verbatim} + + +\section{indication add} +\subsection{Summary} +\begin{verbatim} +Add the given indication to the country +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: indication add <country> <indication> "<tonelist>" + Add the given indication to the country. + +\end{verbatim} + + +\section{indication remove} +\subsection{Summary} +\begin{verbatim} +Remove the given indication from the country +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: indication remove <country> <indication> + Remove the given indication from the country. + +\end{verbatim} + + +\section{indication show} +\subsection{Summary} +\begin{verbatim} +Display a list of all countries/indications +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: indication show [<country> ...] + Display either a condensed for of all country/indications, or the + indications for the specified countries. + +\end{verbatim} + + +\section{jabber debug} +\subsection{Summary} +\begin{verbatim} +Enable Jabber debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: jabber debug + Enables dumping of Jabber packets for debugging purposes. + +\end{verbatim} + + +\section{jabber debug off} +\subsection{Summary} +\begin{verbatim} +Disable Jabber debug +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: jabber debug off + Disables dumping of Jabber packets for debugging purposes. + +\end{verbatim} + + +\section{jabber reload} +\subsection{Summary} +\begin{verbatim} +Reload Jabber configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: jabber reload + Enables reloading of Jabber module. + +\end{verbatim} + + +\section{jabber show connected} +\subsection{Summary} +\begin{verbatim} +Show state of clients and components +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: jabber debug + Enables dumping of Jabber packets for debugging purposes. + +\end{verbatim} + + +\section{jabber test} +\subsection{Summary} +\begin{verbatim} +Shows roster, but is generally used for mog's debugging. +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: jabber test [client] + Sends test message for debugging purposes. A specific client + as configured in jabber.conf can be optionally specified. + +\end{verbatim} + + +\section{keys init} +\subsection{Summary} +\begin{verbatim} +Initialize RSA key passcodes +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: keys init + Initializes private keys (by reading in pass code from the user) + +\end{verbatim} + + +\section{keys show} +\subsection{Summary} +\begin{verbatim} +Displays RSA key information +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: keys show + Displays information about RSA keys known by Asterisk + +\end{verbatim} + + +\section{local show channels} +\subsection{Summary} +\begin{verbatim} +List status of local channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: local show channels + Provides summary information on active local proxy channels. + +\end{verbatim} + + +\section{logger mute} +\subsection{Summary} +\begin{verbatim} +Toggle logging output to a console +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: logger mute + Disables logging output to the current console, making it possible to + gather information without being disturbed by scrolling lines. + +\end{verbatim} + + +\section{logger reload} +\subsection{Summary} +\begin{verbatim} +Reopens the log files +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: logger reload + Reloads the logger subsystem state. Use after restarting syslogd(8) if you are using syslog logging. + +\end{verbatim} + + +\section{logger rotate} +\subsection{Summary} +\begin{verbatim} +Rotates and reopens the log files +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: logger rotate + Rotates and Reopens the log files. + +\end{verbatim} + + +\section{logger show channels} +\subsection{Summary} +\begin{verbatim} +List configured log channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: logger show channels + List configured logger channels. + +\end{verbatim} + + +\section{manager debug} +\subsection{Summary} +\begin{verbatim} +Show, enable, disable debugging of the manager code +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager debug [on|off] + Show, enable, disable debugging of the manager code. + +\end{verbatim} + + +\section{manager dump actiondocs} +\subsection{Summary} +\begin{verbatim} +Dump manager action documentation in LaTeX format +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager dump actiondocs [action] + Dump manager action documentation to /tmp/ast_manager_actiondocs.tex. + +\end{verbatim} + + +\section{manager show command} +\subsection{Summary} +\begin{verbatim} +Show a manager interface command +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager show command <actionname> + Shows the detailed description for a specific Asterisk manager interface command. + +\end{verbatim} + + +\section{manager show commands} +\subsection{Summary} +\begin{verbatim} +List manager interface commands +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager show commands + Prints a listing of all the available Asterisk manager interface commands. + +\end{verbatim} + + +\section{manager show connected} +\subsection{Summary} +\begin{verbatim} +List connected manager interface users +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager show connected + Prints a listing of the users that are currently connected to the +Asterisk manager interface. + +\end{verbatim} + + +\section{manager show eventq} +\subsection{Summary} +\begin{verbatim} +List manager interface queued events +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager show eventq + Prints a listing of all events pending in the Asterisk manger +event queue. + +\end{verbatim} + + +\section{manager show users} +\subsection{Summary} +\begin{verbatim} +List configured manager users +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: manager show users + Prints a listing of all managers that are currently configured on that + system. + +\end{verbatim} + + +\section{manager show user} +\subsection{Summary} +\begin{verbatim} +Display information on a specific manager user +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + Usage: manager show user <user> + Display all information related to the manager user specified. + +\end{verbatim} + + +\section{meetme} +\subsection{Summary} +\begin{verbatim} +Execute a command on a conference or conferee +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: meetme (un)lock|(un)mute|kick|list [concise] <confno> <usernumber> + Executes a command for the conference or on a conferee + +\end{verbatim} + + +\section{memory show allocations} +\subsection{Summary} +\begin{verbatim} +Display outstanding memory allocations +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: memory show allocations [<file>] + Dumps a list of all segments of allocated memory, optionally +limited to those from a specific file + +\end{verbatim} + + +\section{memory show summary} +\subsection{Summary} +\begin{verbatim} +Summarize outstanding memory allocations +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: memory show summary [<file>] + Summarizes heap memory allocations by file, or optionally +by function, if a file is specified + +\end{verbatim} + + +\section{mgcp audit endpoint} +\subsection{Summary} +\begin{verbatim} +Audit specified MGCP endpoint +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: mgcp audit endpoint <endpointid> + Lists the capabilities of an endpoint in the MGCP (Media Gateway Control Protocol) subsystem. + mgcp debug MUST be on to see the results of this command. + +\end{verbatim} + + +\section{mgcp reload} +\subsection{Summary} +\begin{verbatim} +Reload MGCP configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: mgcp reload + Reloads MGCP configuration from mgcp.conf + Deprecated: please use 'reload chan_mgcp.so' instead. + +\end{verbatim} + + +\section{mgcp set debug} +\subsection{Summary} +\begin{verbatim} +Enable MGCP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: mgcp set debug + Enables dumping of MGCP packets for debugging purposes + +\end{verbatim} + + +\section{mgcp set debug off} +\subsection{Summary} +\begin{verbatim} +Disable MGCP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: mgcp set debug off + Disables dumping of MGCP packets for debugging purposes + +\end{verbatim} + + +\section{mgcp show endpoints} +\subsection{Summary} +\begin{verbatim} +List defined MGCP endpoints +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: mgcp show endpoints + Lists all endpoints known to the MGCP (Media Gateway Control Protocol) subsystem. + +\end{verbatim} + + +\section{minivm list accounts} +\subsection{Summary} +\begin{verbatim} +List defined mini-voicemail boxes +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm list accounts + Lists all mailboxes currently set up + +\end{verbatim} + + +\section{minivm list templates} +\subsection{Summary} +\begin{verbatim} +List message templates +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm list templates + Lists message templates for e-mail, paging and IM + +\end{verbatim} + + +\section{minivm list zones} +\subsection{Summary} +\begin{verbatim} +List zone message formats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm list zones + Lists zone message formats + +\end{verbatim} + + +\section{minivm reload} +\subsection{Summary} +\begin{verbatim} +Reload Mini-voicemail configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm reload + Reload mini-voicemail configuration and reset statistics + +\end{verbatim} + + +\section{minivm show settings} +\subsection{Summary} +\begin{verbatim} +Show mini-voicemail general settings +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm show settings + Display Mini-Voicemail general settings + +\end{verbatim} + + +\section{minivm show stats} +\subsection{Summary} +\begin{verbatim} +Show some mini-voicemail statistics +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: minivm show stats + Display Mini-Voicemail counters + +\end{verbatim} + + +\section{mixmonitor} +\subsection{Summary} +\begin{verbatim} +Execute a MixMonitor command. +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +mixmonitor <start|stop> <chan_name> [args] + +The optional arguments are passed to the +MixMonitor application when the 'start' command is used. + +\end{verbatim} + + +\section{module load} +\subsection{Summary} +\begin{verbatim} +Load a module by name +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: module load <module name> + Loads the specified module into Asterisk. + +\end{verbatim} + + +\section{module reload} +\subsection{Summary} +\begin{verbatim} +Reload configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: module reload [module ...] + Reloads configuration files for all listed modules which support + reloading, or for all supported modules if none are listed. + +\end{verbatim} + + +\section{module show [like]} +\subsection{Summary} +\begin{verbatim} +List modules and info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: module show [like keyword] + Shows Asterisk modules currently in use, and usage statistics. + +\end{verbatim} + + +\section{module unload} +\subsection{Summary} +\begin{verbatim} +Unload a module by name +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: module unload [-f|-h] <module_1> [<module_2> ... ] + Unloads the specified module from Asterisk. The -f + option causes the module to be unloaded even if it is + in use (may cause a crash) and the -h module causes the + module to be unloaded even if the module says it cannot, + which almost always will cause a crash. + +\end{verbatim} + + +\section{moh reload} +\subsection{Summary} +\begin{verbatim} +Music On Hold +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Music On Hold +\end{verbatim} + + +\section{moh show classes} +\subsection{Summary} +\begin{verbatim} +List MOH classes +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Lists all MOH classes +\end{verbatim} + + +\section{moh show files} +\subsection{Summary} +\begin{verbatim} +List MOH file-based classes +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Lists all loaded file-based MOH classes and their files +\end{verbatim} + + +\section{no debug channel} +\subsection{Summary} +\begin{verbatim} +Disable debugging on channel(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: core set debug channel <all|channel> [off] + Enables/disables debugging on all or on a specific channel. + +\end{verbatim} + + +\section{odbc show} +\subsection{Summary} +\begin{verbatim} +List ODBC DSN(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: odbc show [<class>] + List settings of a particular ODBC class. + or, if not specified, all classes. + +\end{verbatim} + + +\section{originate} +\subsection{Summary} +\begin{verbatim} +Originate a call +\end{verbatim} +\subsection{Usage} +\begin{verbatim} + There are two ways to use this command. A call can be originated between a +channel and a specific application, or between a channel and an extension in +the dialplan. This is similar to call files or the manager originate action. +Calls originated with this command are given a timeout of 30 seconds. + +Usage1: originate <tech/data> application <appname> [appdata] + This will originate a call between the specified channel tech/data and the +given application. Arguments to the application are optional. If the given +arguments to the application include spaces, all of the arguments to the +application need to be placed in quotation marks. + +Usage2: originate <tech/data> extension [exten@][context] + This will originate a call between the specified channel tech/data and the +given extension. If no context is specified, the 'default' context will be +used. If no extension is given, the 's' extension will be used. + +\end{verbatim} + + +\section{parkedcalls show} +\subsection{Summary} +\begin{verbatim} +List currently parked calls +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: parkedcalls show + List currently parked calls + +\end{verbatim} + + +\section{queue add member} +\subsection{Summary} +\begin{verbatim} +Add a channel to a specified queue +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: queue add member <channel> to <queue> [penalty <penalty>] + +\end{verbatim} + + +\section{queue remove member} +\subsection{Summary} +\begin{verbatim} +Removes a channel from a specified queue +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: queue remove member <channel> from <queue> + +\end{verbatim} + + +\section{queue show} +\subsection{Summary} +\begin{verbatim} +Show status of a specified queue +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: queue show + Provides summary information on a specified queue. + +\end{verbatim} + + +\section{realtime load} +\subsection{Summary} +\begin{verbatim} +Used to print out RealTime variables. +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: realtime load <family> <colmatch> <value> + Prints out a list of variables using the RealTime driver. + +\end{verbatim} + + +\section{realtime update} +\subsection{Summary} +\begin{verbatim} +Used to update RealTime variables. +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: realtime update <family> <colmatch> <value> + Update a single variable using the RealTime driver. + +\end{verbatim} + + +\section{restart gracefully} +\subsection{Summary} +\begin{verbatim} +Restart Asterisk gracefully +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: restart gracefully + Causes Asterisk to stop accepting new calls and exec() itself performing a cold + restart when all active calls have ended. + +\end{verbatim} + + +\section{restart now} +\subsection{Summary} +\begin{verbatim} +Restart Asterisk immediately +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: restart now + Causes Asterisk to hangup all calls and exec() itself performing a cold + restart. + +\end{verbatim} + + +\section{restart when convenient} +\subsection{Summary} +\begin{verbatim} +Restart Asterisk at empty call volume +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: restart when convenient + Causes Asterisk to perform a cold restart when all active calls have ended. + +\end{verbatim} + + +\section{rpt debug level} +\subsection{Summary} +\begin{verbatim} +Enable app_rpt debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt debug level {0-7} + Enables debug messages in app_rpt + +\end{verbatim} + + +\section{rpt dump} +\subsection{Summary} +\begin{verbatim} +Dump app_rpt structs for debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt dump <nodename> + Dumps struct debug info to log + +\end{verbatim} + + +\section{rpt lstats} +\subsection{Summary} +\begin{verbatim} +Dump link statistics +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt lstats <nodename> + Dumps link statistics to console + +\end{verbatim} + + +\section{rpt reload} +\subsection{Summary} +\begin{verbatim} +Reload app_rpt config +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt reload + Reloads app_rpt running config parameters + +\end{verbatim} + + +\section{rpt restart} +\subsection{Summary} +\begin{verbatim} +Restart app_rpt +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt restart + Restarts app_rpt + +\end{verbatim} + + +\section{rpt stats} +\subsection{Summary} +\begin{verbatim} +Dump node statistics +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rpt stats <nodename> + Dumps node statistics to console + +\end{verbatim} + + +\section{rtcp debug ip} +\subsection{Summary} +\begin{verbatim} +Enable RTCP debugging on IP +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtcp debug [ip host[:port]] + Enable dumping of all RTCP packets to and from host. + +\end{verbatim} + + +\section{rtcp debug} +\subsection{Summary} +\begin{verbatim} +Enable RTCP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtcp debug [ip host[:port]] + Enable dumping of all RTCP packets to and from host. + +\end{verbatim} + + +\section{rtcp debug off} +\subsection{Summary} +\begin{verbatim} +Disable RTCP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtcp debug off + Disable all RTCP debugging + +\end{verbatim} + + +\section{rtcp stats} +\subsection{Summary} +\begin{verbatim} +Enable RTCP stats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtcp stats + Enable dumping of RTCP stats. + +\end{verbatim} + + +\section{rtcp stats off} +\subsection{Summary} +\begin{verbatim} +Disable RTCP stats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtcp stats off + Disable all RTCP stats + +\end{verbatim} + + +\section{rtp debug ip} +\subsection{Summary} +\begin{verbatim} +Enable RTP debugging on IP +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtp debug [ip host[:port]] + Enable dumping of all RTP packets to and from host. + +\end{verbatim} + + +\section{rtp debug} +\subsection{Summary} +\begin{verbatim} +Enable RTP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtp debug [ip host[:port]] + Enable dumping of all RTP packets to and from host. + +\end{verbatim} + + +\section{rtp debug off} +\subsection{Summary} +\begin{verbatim} +Disable RTP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: rtp debug off + Disable all RTP debugging + +\end{verbatim} + + +\section{say load} +\subsection{Summary} +\begin{verbatim} +set/show the say mode +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +say load new|old +\end{verbatim} + + +\section{sip history} +\subsection{Summary} +\begin{verbatim} +Enable SIP history +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip history + Enables recording of SIP dialog history for debugging purposes. +Use 'sip show history' to view the history of a call number. + +\end{verbatim} + + +\section{sip history off} +\subsection{Summary} +\begin{verbatim} +Disable SIP history +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip history off + Disables recording of SIP dialog history for debugging purposes + +\end{verbatim} + + +\section{sip notify} +\subsection{Summary} +\begin{verbatim} +Send a notify packet to a SIP peer +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip notify <type> <peer> [<peer>...] + Send a NOTIFY message to a SIP peer or peers + Message types are defined in sip_notify.conf + +\end{verbatim} + + +\section{sip prune realtime} +\subsection{Summary} +\begin{verbatim} +Prune cached Realtime object(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip prune realtime [peer|user] [<name>|all|like <pattern>] + Prunes object(s) from the cache. + Optional regular expression pattern is used to filter the objects. + +\end{verbatim} + + +\section{sip prune realtime peer} +\subsection{Summary} +\begin{verbatim} +Prune cached Realtime peer(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip prune realtime [peer|user] [<name>|all|like <pattern>] + Prunes object(s) from the cache. + Optional regular expression pattern is used to filter the objects. + +\end{verbatim} + + +\section{sip prune realtime user} +\subsection{Summary} +\begin{verbatim} +Prune cached Realtime user(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip prune realtime [peer|user] [<name>|all|like <pattern>] + Prunes object(s) from the cache. + Optional regular expression pattern is used to filter the objects. + +\end{verbatim} + + +\section{sip reload} +\subsection{Summary} +\begin{verbatim} +Reload SIP configuration +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip reload + Reloads SIP configuration from sip.conf + +\end{verbatim} + + +\section{sip set debug} +\subsection{Summary} +\begin{verbatim} +Enable SIP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip set debug {on|off|ip <host[:PORT]>|peer <peername>} + sip set debug on + Enables dumping of all SIP messages for debugging purposes + + sip set debug off + Disables dumping of all SIP messages + + sip set debug ip <host[:PORT]> + Enables dumping of SIP messages to and from host. + + sip set debug peer <peername> + Enables dumping of SIP messages to and from peer's IP. + Requires peer to be registered. + +\end{verbatim} + + +\section{sip set debug ip} +\subsection{Summary} +\begin{verbatim} +Enable SIP debugging on IP +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip set debug {on|off|ip <host[:PORT]>|peer <peername>} + sip set debug on + Enables dumping of all SIP messages for debugging purposes + + sip set debug off + Disables dumping of all SIP messages + + sip set debug ip <host[:PORT]> + Enables dumping of SIP messages to and from host. + + sip set debug peer <peername> + Enables dumping of SIP messages to and from peer's IP. + Requires peer to be registered. + +\end{verbatim} + + +\section{sip set debug off} +\subsection{Summary} +\begin{verbatim} +Disable SIP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip set debug off + Disables dumping of SIP packets for debugging purposes + +\end{verbatim} + + +\section{sip set debug on} +\subsection{Summary} +\begin{verbatim} +Enable SIP debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip set debug {on|off|ip <host[:PORT]>|peer <peername>} + sip set debug on + Enables dumping of all SIP messages for debugging purposes + + sip set debug off + Disables dumping of all SIP messages + + sip set debug ip <host[:PORT]> + Enables dumping of SIP messages to and from host. + + sip set debug peer <peername> + Enables dumping of SIP messages to and from peer's IP. + Requires peer to be registered. + +\end{verbatim} + + +\section{sip set debug peer} +\subsection{Summary} +\begin{verbatim} +Enable SIP debugging on Peername +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip set debug {on|off|ip <host[:PORT]>|peer <peername>} + sip set debug on + Enables dumping of all SIP messages for debugging purposes + + sip set debug off + Disables dumping of all SIP messages + + sip set debug ip <host[:PORT]> + Enables dumping of SIP messages to and from host. + + sip set debug peer <peername> + Enables dumping of SIP messages to and from peer's IP. + Requires peer to be registered. + +\end{verbatim} + + +\section{sip show channels} +\subsection{Summary} +\begin{verbatim} +List active SIP channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show channels + Lists all currently active SIP channels. + +\end{verbatim} + + +\section{sip show channel} +\subsection{Summary} +\begin{verbatim} +Show detailed SIP channel info +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show channel <channel> + Provides detailed status on a given SIP channel. + +\end{verbatim} + + +\section{sip show domains} +\subsection{Summary} +\begin{verbatim} +List our local SIP domains. +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show domains + Lists all configured SIP local domains. + Asterisk only responds to SIP messages to local domains. + +\end{verbatim} + + +\section{sip show history} +\subsection{Summary} +\begin{verbatim} +Show SIP dialog history +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show history <channel> + Provides detailed dialog history on a given SIP channel. + +\end{verbatim} + + +\section{sip show inuse} +\subsection{Summary} +\begin{verbatim} +List all inuse/limits +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show inuse [all] + List all SIP users and peers usage counters and limits. + Add option "all" to show all devices, not only those with a limit. + +\end{verbatim} + + +\section{sip show objects} +\subsection{Summary} +\begin{verbatim} +List all SIP object allocations +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show objects + Lists status of known SIP objects + +\end{verbatim} + + +\section{sip show peers} +\subsection{Summary} +\begin{verbatim} +List defined SIP peers +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show peers [like <pattern>] + Lists all known SIP peers. + Optional regular expression pattern is used to filter the peer list. + +\end{verbatim} + + +\section{sip show peer} +\subsection{Summary} +\begin{verbatim} +Show details on specific SIP peer +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show peer <name> [load] + Shows all details on one SIP peer and the current status. + Option "load" forces lookup of peer in realtime storage. + +\end{verbatim} + + +\section{sip show registry} +\subsection{Summary} +\begin{verbatim} +List SIP registration status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show registry + Lists all registration requests and status. + +\end{verbatim} + + +\section{sip show settings} +\subsection{Summary} +\begin{verbatim} +Show SIP global settings +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show settings + Provides detailed list of the configuration of the SIP channel. + +\end{verbatim} + + +\section{sip show subscriptions} +\subsection{Summary} +\begin{verbatim} +List active SIP subscriptions +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show subscriptions + Lists active SIP subscriptions for extension states + +\end{verbatim} + + +\section{sip show users} +\subsection{Summary} +\begin{verbatim} +List defined SIP users +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show users [like <pattern>] + Lists all known SIP users. + Optional regular expression pattern is used to filter the user list. + +\end{verbatim} + + +\section{sip show user} +\subsection{Summary} +\begin{verbatim} +Show details on specific SIP user +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip show user <name> [load] + Shows all details on one SIP user and the current status. + Option "load" forces lookup of peer in realtime storage. + +\end{verbatim} + + +\section{sip unregister} +\subsection{Summary} +\begin{verbatim} +Unregister (force expiration) a SIP peer from the registery + +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sip unregister <peer> + Unregister (force expiration) a SIP peer from the registry + +\end{verbatim} + + +\section{skinny reset} +\subsection{Summary} +\begin{verbatim} +Reset Skinny device(s) +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: skinny reset <DeviceId|all> [restart] + Causes a Skinny device to reset itself, optionally with a full restart + +\end{verbatim} + + +\section{skinny set debug} +\subsection{Summary} +\begin{verbatim} +Enable Skinny debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: skinny set debug + Enables dumping of Skinny packets for debugging purposes + +\end{verbatim} + + +\section{skinny set debug off} +\subsection{Summary} +\begin{verbatim} +Disable Skinny debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: skinny set debug off + Disables dumping of Skinny packets for debugging purposes + +\end{verbatim} + + +\section{skinny show devices} +\subsection{Summary} +\begin{verbatim} +List defined Skinny devices +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: skinny show devices + Lists all devices known to the Skinny subsystem. + +\end{verbatim} + + +\section{skinny show lines} +\subsection{Summary} +\begin{verbatim} +List defined Skinny lines per device +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: skinny show lines + Lists all lines known to the Skinny subsystem. + +\end{verbatim} + + +\section{sla show stations} +\subsection{Summary} +\begin{verbatim} +Show SLA Stations +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sla show stations + This will list all stations defined in sla.conf + +\end{verbatim} + + +\section{sla show trunks} +\subsection{Summary} +\begin{verbatim} +Show SLA Trunks +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: sla show trunks + This will list all trunks defined in sla.conf + +\end{verbatim} + + +\section{soft hangup} +\subsection{Summary} +\begin{verbatim} +Request a hangup on a given channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: soft hangup <channel> + Request that a channel be hung up. The hangup takes effect + the next time the driver reads or writes from the channel + +\end{verbatim} + + +\section{stop gracefully} +\subsection{Summary} +\begin{verbatim} +Gracefully shut down Asterisk +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: stop gracefully + Causes Asterisk to not accept new calls, and exit when all + active calls have terminated normally. + +\end{verbatim} + + +\section{stop now} +\subsection{Summary} +\begin{verbatim} +Shut down Asterisk immediately +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: stop now + Shuts down a running Asterisk immediately, hanging up all active calls . + +\end{verbatim} + + +\section{stop when convenient} +\subsection{Summary} +\begin{verbatim} +Shut down Asterisk at empty call volume +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: stop when convenient + Causes Asterisk to perform a shutdown when all active calls have ended. + +\end{verbatim} + + +\section{stun debug} +\subsection{Summary} +\begin{verbatim} +Enable STUN debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: stun debug + Enable STUN (Simple Traversal of UDP through NATs) debugging + +\end{verbatim} + + +\section{stun debug off} +\subsection{Summary} +\begin{verbatim} +Disable STUN debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: stun debug off + Disable STUN debugging + +\end{verbatim} + + +\section{udptl debug} +\subsection{Summary} +\begin{verbatim} +Enable UDPTL debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: udptl debug [ip host[:port]] + Enable dumping of all UDPTL packets to and from host. + +\end{verbatim} + + +\section{udptl debug ip} +\subsection{Summary} +\begin{verbatim} +Enable UDPTL debugging on IP +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: udptl debug [ip host[:port]] + Enable dumping of all UDPTL packets to and from host. + +\end{verbatim} + + +\section{udptl debug off} +\subsection{Summary} +\begin{verbatim} +Disable UDPTL debugging +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: udptl debug off + Disable all UDPTL debugging + +\end{verbatim} + + +\section{ulimit} +\subsection{Summary} +\begin{verbatim} +Set or show process resource limits +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: ulimit {-d|-l|-f|-m|-s|-t|-u|-v|-c|-n} [<num>] + Shows or sets the corresponding resource limit. + -d Process data segment [readonly] + -l Memory lock size [readonly] + -f File size + -m Process resident memory [readonly] + -s Process stack size [readonly] + -t CPU usage [readonly] + -u Child processes + -v Process virtual memory [readonly] + -c Core dump file size + -n Number of file descriptors + +\end{verbatim} + + +\section{voicemail show users} +\subsection{Summary} +\begin{verbatim} +List defined voicemail boxes +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: voicemail show users [for <context>] + Lists all mailboxes currently set up + +\end{verbatim} + + +\section{voicemail show zones} +\subsection{Summary} +\begin{verbatim} +List zone message formats +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: voicemail show zones + Lists zone message formats + +\end{verbatim} + + +\section{zap destroy channel} +\subsection{Summary} +\begin{verbatim} +Destroy a channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap destroy channel <chan num> + DON'T USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING. Immediately removes a given channel, whether it is in use or not + +\end{verbatim} + + +\section{zap restart} +\subsection{Summary} +\begin{verbatim} +Fully restart zaptel channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap restart + Restarts the zaptel channels: destroys them all and then + re-reads them from zapata.conf. + Note that this will STOP any running CALL on zaptel channels. + +\end{verbatim} + + +\section{zap show cadences} +\subsection{Summary} +\begin{verbatim} +List cadences +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap show cadences + Shows all cadences currently defined + +\end{verbatim} + + +\section{zap show channels} +\subsection{Summary} +\begin{verbatim} +Show active zapata channels +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap show channels [ trunkgroup <trunkgroup> | group <group> | context <context> ] + Shows a list of available channels with optional filtering + <group> must be a number between 0 and 63 + +\end{verbatim} + + +\section{zap show channel} +\subsection{Summary} +\begin{verbatim} +Show information on a channel +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap show channel <chan num> + Detailed information about a given channel + +\end{verbatim} + + +\section{zap show status} +\subsection{Summary} +\begin{verbatim} +Show all Zaptel cards status +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap show status + Shows a list of Zaptel cards with status + +\end{verbatim} + + +\section{zap show version} +\subsection{Summary} +\begin{verbatim} +Show the Zaptel version in use +\end{verbatim} +\subsection{Usage} +\begin{verbatim} +Usage: zap show version + Shows the Zaptel version in use + +\end{verbatim} + + diff --git a/doc/tex/ast_funcdocs.tex b/doc/tex/ast_funcdocs.tex new file mode 100644 index 000000000..280308b25 --- /dev/null +++ b/doc/tex/ast_funcdocs.tex @@ -0,0 +1,1704 @@ +% This file is automatically generated by the "core dump funcdocs" CLI command. Any manual edits will be lost. +\section{AGENT} +\subsection{Syntax} +\begin{verbatim} +AGENT(<agentid>[:item]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets information about an Agent +\end{verbatim} +\subsection{Description} +\begin{verbatim} +The valid items to retrieve are: +- status (default) The status of the agent + LOGGEDIN | LOGGEDOUT +- password The password of the agent +- name The name of the agent +- mohclass MusicOnHold class +- exten The callback extension for the Agent (AgentCallbackLogin) +- channel The name of the active channel for the Agent (AgentLogin) + +\end{verbatim} + + +\section{ARRAY} +\subsection{Syntax} +\begin{verbatim} +ARRAY(var1[|var2[...][|varN]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Allows setting multiple variables at once +\end{verbatim} +\subsection{Description} +\begin{verbatim} +The comma-separated list passed as a value to which the function is set will +be interpreted as a set of values to which the comma-separated list of +variable names in the argument should be set. +Hence, Set(ARRAY(var1|var2)=1\,2) will set var1 to 1 and var2 to 2 +Note: remember to either backslash your commas in extensions.conf or quote the +entire argument, since Set can take multiple arguments itself. + +\end{verbatim} + + +\section{BASE64\_DECODE} +\subsection{Syntax} +\begin{verbatim} +BASE64_DECODE(<base64_string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Decode a base64 string +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns the plain text string + +\end{verbatim} + + +\section{BASE64\_ENCODE} +\subsection{Syntax} +\begin{verbatim} +BASE64_ENCODE(<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Encode a string in base64 +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns the base64 string + +\end{verbatim} + + +\section{BLACKLIST} +\subsection{Syntax} +\begin{verbatim} +BLACKLIST() +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Check if the callerid is on the blacklist +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Uses astdb to check if the Caller*ID is in family 'blacklist'. Returns 1 or 0. + +\end{verbatim} + + +\section{CALLERID} +\subsection{Syntax} +\begin{verbatim} +CALLERID(datatype[,<optional-CID>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets Caller*ID data on the channel. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets or sets Caller*ID data on the channel. The allowable datatypes +are "all", "name", "num", "ANI", "DNID", "RDNIS", "pres", +and "ton". +Uses channel callerid by default or optional callerid, if specified. + +\end{verbatim} + + +\section{CALLERPRES} +\subsection{Syntax} +\begin{verbatim} +CALLERPRES() +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets Caller*ID presentation on the channel. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets or sets Caller*ID presentation on the channel. The following values +are valid: + allowed_not_screened : Presentation Allowed, Not Screened + allowed_passed_screen : Presentation Allowed, Passed Screen + allowed_failed_screen : Presentation Allowed, Failed Screen + allowed : Presentation Allowed, Network Number + prohib_not_screened : Presentation Prohibited, Not Screened + prohib_passed_screen : Presentation Prohibited, Passed Screen + prohib_failed_screen : Presentation Prohibited, Failed Screen + prohib : Presentation Prohibited, Network Number + unavailable : Number Unavailable + +\end{verbatim} + + +\section{CDR} +\subsection{Syntax} +\begin{verbatim} +CDR(<name>[|options]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets a CDR variable +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Options: + 'r' searches the entire stack of CDRs on the channel + 'u' retrieves the raw, unprocessed value + For example, 'start', 'answer', and 'end' will be retrieved as epoch + values, when the 'u' option is passed, but formatted as YYYY-MM-DD HH:MM:SS + otherwise. Similarly, disposition and amaflags will return their raw + integral values. + Here is a list of all the available cdr field names: + clid lastdata disposition + src start amaflags + dst answer accountcode + dcontext end uniqueid + dstchannel duration userfield + lastapp billsec channel + All of the above variables are read-only, except for accountcode, + userfield, and amaflags. You may, however, supply + a name not on the above list, and create your own + variable, whose value can be changed with this function, + and this variable will be stored on the cdr. + raw values for disposition: + 1 = NO ANSWER + 2 = BUSY + 3 = FAILED + 4 = ANSWERED + raw values for amaflags: + 1 = OMIT + 2 = BILLING + 3 = DOCUMENTATION + +\end{verbatim} + + +\section{CHANNEL} +\subsection{Syntax} +\begin{verbatim} +CHANNEL(item) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets/sets various pieces of information about the channel. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets/set various pieces of information about the channel. +Standard items (provided by all channel technologies) are: +R/O audioreadformat format currently being read +R/O audionativeformat format used natively for audio +R/O audiowriteformat format currently being written +R/W callgroup call groups for call pickup +R/O channeltype technology used for channel +R/W language language for sounds played +R/W musicclass class (from musiconhold.conf) for hold music +R/W rxgain set rxgain level on channel drivers that support it +R/O state state for channel +R/W tonezone zone for indications played +R/W txgain set txgain level on channel drivers that support it +R/O videonativeformat format used natively for video + +chan_sip provides the following additional options: +R/O rtpqos Get QOS information about the RTP stream + This option takes two additional arguments: + Argument 1: + audio Get data about the audio stream + video Get data about the video stream + text Get data about the text stream + Argument 2: + local_ssrc Local SSRC (stream ID) + local_lostpackets Local lost packets + local_jitter Local calculated jitter + local_count Number of received packets + remote_ssrc Remote SSRC (stream ID) + remote_lostpackets Remote lost packets + remote_jitter Remote reported jitter + remote_count Number of transmitted packets + rtt Round trip time + all All statistics (in a form suited to logging, but not for parsing) +R/O rtpdest Get remote RTP destination information + This option takes one additional argument: + Argument 1: + audio Get audio destination + video Get video destination + +chan_iax2 provides the following additional options: +R/W osptoken Get or set the OSP token information for a call + +Additional items may be available from the channel driver providing +the channel; see its documentation for details. + +Any item requested that is not available on the current channel will +return an empty string. + +\end{verbatim} + + +\section{CHECKSIPDOMAIN} +\subsection{Syntax} +\begin{verbatim} +CHECKSIPDOMAIN(<domain|IP>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Checks if domain is a local domain +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function checks if the domain in the argument is configured +as a local SIP domain that this Asterisk server is configured to handle. +Returns the domain name if it is locally handled, otherwise an empty string. +Check the domain= configuration in sip.conf + +\end{verbatim} + + +\section{CURL} +\subsection{Syntax} +\begin{verbatim} +CURL(url[|post-data]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Retrieves the contents of a URL +\end{verbatim} +\subsection{Description} +\begin{verbatim} + url - URL to retrieve + post-data - Optional data to send as a POST (GET is default action) + +\end{verbatim} + + +\section{CUT} +\subsection{Syntax} +\begin{verbatim} +CUT(<varname>,<char-delim>,<range-spec>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Slices and dices strings, based upon a named delimiter. +\end{verbatim} +\subsection{Description} +\begin{verbatim} + varname - variable you want cut + char-delim - defaults to '-' + range-spec - number of the field you want (1-based offset) + may also be specified as a range (with -) + or group of ranges and fields (with &) + +\end{verbatim} + + +\section{DB} +\subsection{Syntax} +\begin{verbatim} +DB(<family>/<key>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Read from or write to the Asterisk database +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will read from or write a value to the Asterisk database. On a +read, this function returns the corresponding value from the database, or blank +if it does not exist. Reading a database value will also set the variable +DB_RESULT. If you wish to find out if an entry exists, use the DB_EXISTS +function. + +\end{verbatim} + + +\section{DB\_DELETE} +\subsection{Syntax} +\begin{verbatim} +DB_DELETE(<family>/<key>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Return a value from the database and delete it +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will retrieve a value from the Asterisk database + and then remove that key from the database. DB_RESULT +will be set to the key's value if it exists. + +\end{verbatim} + + +\section{DB\_EXISTS} +\subsection{Syntax} +\begin{verbatim} +DB_EXISTS(<family>/<key>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Check to see if a key exists in the Asterisk database +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will check to see if a key exists in the Asterisk +database. If it exists, the function will return "1". If not, +it will return "0". Checking for existence of a database key will +also set the variable DB_RESULT to the key's value if it exists. + +\end{verbatim} + + +\section{DEVSTATE} +\subsection{Syntax} +\begin{verbatim} +DEVSTATE(device) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Get or Set a device state +\end{verbatim} +\subsection{Description} +\begin{verbatim} + The DEVSTATE function can be used to retrieve the device state from any +device state provider. For example: + NoOp(SIP/mypeer has state ${DEVSTATE(SIP/mypeer)}) + NoOp(Conference number 1234 has state ${DEVSTATE(MeetMe:1234)}) + + The DEVSTATE function can also be used to set custom device state from +the dialplan. The "Custom:" prefix must be used. For example: + Set(DEVSTATE(Custom:lamp1)=BUSY) + Set(DEVSTATE(Custom:lamp2)=NOT_INUSE) +You can subscribe to the status of a custom device state using a hint in +the dialplan: + exten => 1234,hint,Custom:lamp1 + + The possible values for both uses of this function are: +UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING +RINGINUSE | ONHOLD + +\end{verbatim} + + +\section{DUNDILOOKUP} +\subsection{Syntax} +\begin{verbatim} +DUNDILOOKUP(number[|context[|options]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Do a DUNDi lookup of a phone number. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This will do a DUNDi lookup of the given phone number. +If no context is given, the default will be e164. The result of +this function will return the Technology/Resource found in the first result +in the DUNDi lookup. If no results were found, the result will be blank. +If the 'b' option is specified, the internal DUNDi cache will +be bypassed. + +\end{verbatim} + + +\section{DUNDIQUERY} +\subsection{Syntax} +\begin{verbatim} +DUNDIQUERY(number[|context[|options]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Initiate a DUNDi query. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This will do a DUNDi lookup of the given phone number. +If no context is given, the default will be e164. The result of +this function will be a numeric ID that can be used to retrieve +the results with the DUNDIRESULT function. If the 'b' option is +is specified, the internal DUNDi cache will be bypassed. + +\end{verbatim} + + +\section{DUNDIRESULT} +\subsection{Syntax} +\begin{verbatim} +DUNDIRESULT(id|resultnum) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Retrieve results from a DUNDIQUERY +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will retrieve results from a previous use +of the DUNDIQUERY function. + id - This argument is the identifier returned by the DUNDIQUERY function. + resultnum - This is the number of the result that you want to retrieve. + Results start at 1. If this argument is specified as "getnum", + then it will return the total number of results that are available. + +\end{verbatim} + + +\section{ENUMLOOKUP} +\subsection{Syntax} +\begin{verbatim} +ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +General or specific querying of NAPTR records for ENUM or ENUM-like DNS pointers +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Option 'c' returns an integer count of the number of NAPTRs of a certain RR type. +Combination of 'c' and Method-type of 'ALL' will return a count of all NAPTRs for the record. +Defaults are: Method-type=sip, no options, record=1, zone-suffix=e164.arpa + +For more information, see doc/asterisk.pdf +\end{verbatim} + + +\section{ENUMQUERY} +\subsection{Syntax} +\begin{verbatim} +ENUMQUERY(number[|Method-type[|zone-suffix]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Initiate an ENUM query +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This will do a ENUM lookup of the given phone number. +If no method-tpye is given, the default will be sip. If no +zone-suffix is given, the default will be "e164.arpa". +The result of this function will be a numeric ID that can +be used to retrieve the results using the ENUMRESULT function. + +\end{verbatim} + + +\section{ENUMRESULT} +\subsection{Syntax} +\begin{verbatim} +ENUMRESULT(id|resultnum) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Retrieve results from a ENUMQUERY +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will retrieve results from a previous use +of the ENUMQUERY function. + id - This argument is the identifier returned by the ENUMQUERY function. + resultnum - This is the number of the result that you want to retrieve. + Results start at 1. If this argument is specified as "getnum", + then it will return the total number of results that are available. + +\end{verbatim} + + +\section{ENV} +\subsection{Syntax} +\begin{verbatim} +ENV(<envname>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets the environment variable specified +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{EVAL} +\subsection{Syntax} +\begin{verbatim} +EVAL(<variable>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Evaluate stored variables. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Using EVAL basically causes a string to be evaluated twice. +When a variable or expression is in the dialplan, it will be +evaluated at runtime. However, if the result of the evaluation +is in fact a variable or expression, using EVAL will have it +evaluated a second time. For example, if the variable ${MYVAR} +contains "${OTHERVAR}", then the result of putting ${EVAL(${MYVAR})} +in the dialplan will be the contents of the variable, OTHERVAR. +Normally, by just putting ${MYVAR} in the dialplan, you would be +left with "${OTHERVAR}". + +\end{verbatim} + + +\section{EXISTS} +\subsection{Syntax} +\begin{verbatim} +EXISTS(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Existence Test: Returns 1 if exists, 0 otherwise +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{FIELDQTY} +\subsection{Syntax} +\begin{verbatim} +FIELDQTY(<varname>|<delim>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Count the fields, with an arbitrary delimiter +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{FILTER} +\subsection{Syntax} +\begin{verbatim} +FILTER(<allowed-chars>|<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Filter the string to include only the allowed characters +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{GLOBAL} +\subsection{Syntax} +\begin{verbatim} +GLOBAL(<varname>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets the global variable specified +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{GROUP} +\subsection{Syntax} +\begin{verbatim} +GROUP([category]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets the channel group. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets or sets the channel group. + +\end{verbatim} + + +\section{GROUP\_COUNT} +\subsection{Syntax} +\begin{verbatim} +GROUP_COUNT([groupname][@category]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Counts the number of channels in the specified group +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Calculates the group count for the specified group, or uses the +channel's current group if not specifed (and non-empty). + +\end{verbatim} + + +\section{GROUP\_LIST} +\subsection{Syntax} +\begin{verbatim} +GROUP_LIST() +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets a list of the groups set on a channel. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets a list of the groups set on a channel. + +\end{verbatim} + + +\section{GROUP\_MATCH\_COUNT} +\subsection{Syntax} +\begin{verbatim} +GROUP_MATCH_COUNT(groupmatch[@category]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Counts the number of channels in the groups matching the specified pattern +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Calculates the group count for all groups that match the specified pattern. +Uses standard regular expression matching (see regex(7)). + +\end{verbatim} + + +\section{HASH} +\subsection{Syntax} +\begin{verbatim} +HASH(hashname[|hashkey]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Implementation of a dialplan associative array +\end{verbatim} +\subsection{Description} +\begin{verbatim} +In two argument mode, gets and sets values to corresponding keys within a named +associative array. The single-argument mode will only work when assigned to from +a function defined by func_odbc.so. + +\end{verbatim} + + +\section{HASHKEYS} +\subsection{Syntax} +\begin{verbatim} +HASHKEYS(<hashname>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Retrieve the keys of a HASH() +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns a comma-delimited list of the current keys of an associative array +defined by the HASH() function. Note that if you iterate over the keys of +the result, adding keys during iteration will cause the result of the HASHKEYS +function to change. + +\end{verbatim} + + +\section{IAXPEER} +\subsection{Syntax} +\begin{verbatim} +IAXPEER(<peername|CURRENTCHANNEL>[|item]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets IAX peer information +\end{verbatim} +\subsection{Description} +\begin{verbatim} +If peername specified, valid items are: +- ip (default) The IP address. +- status The peer's status (if qualify=yes) +- mailbox The configured mailbox. +- context The configured context. +- expire The epoch time of the next expire. +- dynamic Is it dynamic? (yes/no). +- callerid_name The configured Caller ID name. +- callerid_num The configured Caller ID number. +- codecs The configured codecs. +- codec[x] Preferred codec index number 'x' (beginning with zero). + +If CURRENTCHANNEL specified, returns IP address of current channel + + +\end{verbatim} + + +\section{IAXVAR} +\subsection{Syntax} +\begin{verbatim} +IAXVAR(<varname>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Sets or retrieves a remote variable +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ICONV} +\subsection{Syntax} +\begin{verbatim} +ICONV(in-charset,out-charset,string) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Converts charsets of strings. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Converts string from in-charset into out-charset. For available charsets, +use 'iconv -l' on your shell command line. +Note: due to limitations within the API, ICONV will not currently work with +charsets with embedded NULLs. If found, the string will terminate. + +\end{verbatim} + + +\section{IF} +\subsection{Syntax} +\begin{verbatim} +IF(<expr>?[<true>][:<false>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Conditional: Returns the data following '?' if true else the data following ':' +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{IFMODULE} +\subsection{Syntax} +\begin{verbatim} +IFMODULE(<modulename.so>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Checks if an Asterisk module is loaded in memory +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Checks if a module is loaded. Use the full module name +as shown by the list in "module list". +Returns "1" if module exists in memory, otherwise "0". + +\end{verbatim} + + +\section{IFTIME} +\subsection{Syntax} +\begin{verbatim} +IFTIME(<timespec>?[<true>][:<false>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Temporal Conditional: Returns the data following '?' if true else the data following ':' +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ISNULL} +\subsection{Syntax} +\begin{verbatim} +ISNULL(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +NULL Test: Returns 1 if NULL or 0 otherwise +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{KEYPADHASH} +\subsection{Syntax} +\begin{verbatim} +KEYPADHASH(<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Hash the letters in the string into the equivalent keypad numbers. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Example: ${KEYPADHASH(Les)} returns "537" + +\end{verbatim} + + +\section{LEN} +\subsection{Syntax} +\begin{verbatim} +LEN(<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Returns the length of the argument given +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{LOCAL} +\subsection{Syntax} +\begin{verbatim} +LOCAL(<varname>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Variables local to the gosub stack frame +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{MAILBOX\_EXISTS} +\subsection{Syntax} +\begin{verbatim} +MAILBOX_EXISTS(<vmbox>[@<context>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Tell if a mailbox is configured +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns a boolean of whether the corresponding mailbox exists. If context +is not specified, defaults to the "default" context. + +\end{verbatim} + + +\section{MATH} +\subsection{Syntax} +\begin{verbatim} +MATH(<number1><op><number2>[,<type_of_result>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Performs Mathematical Functions +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Perform calculation on number1 to number2. Valid ops are: + +,-,/,*,%,<<,>>,^,AND,OR,XOR,<,>,>=,<=,== +and behave as their C equivalents. +<type_of_result> - wanted type of result: + f, float - float(default) + i, int - integer, + h, hex - hex, + c, char - char +Example: Set(i=${MATH(123%16,int)}) - sets var i=11 +\end{verbatim} + + +\section{MD5} +\subsection{Syntax} +\begin{verbatim} +MD5(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Computes an MD5 digest +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{MINIVMACCOUNT} +\subsection{Syntax} +\begin{verbatim} +MINIVMACCOUNT(<account>:item) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets MiniVoicemail account information +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Valid items are: +- path Path to account mailbox (if account exists, otherwise temporary mailbox) +- hasaccount 1 if static Minivm account exists, 0 otherwise +- fullname Full name of account owner +- email Email address used for account +- etemplate E-mail template for account (default template if none is configured) +- ptemplate Pager template for account (default template if none is configured) +- accountcode Account code for voicemail account +- pincode Pin code for voicemail account +- timezone Time zone for voicemail account +- language Language for voicemail account +- <channel variable name> Channel variable value (set in configuration for account) + + +\end{verbatim} + + +\section{MINIVMCOUNTER} +\subsection{Syntax} +\begin{verbatim} +MINIVMCOUNTER(<account>:name[:operand]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Reads or sets counters for MiniVoicemail message +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Valid operands for changing the value of a counter when assigning a value are: +- i Increment by value +- d Decrement by value +- s Set to value + +The counters never goes below zero. +- The name of the counter is a string, up to 10 characters +- If account is given and it exists, the counter is specific for the account +- If account is a domain and the domain directory exists, counters are specific for a domain +The operation is atomic and the counter is locked while changing the value + +The counters are stored as text files in the minivm account directories. It might be better to use +realtime functions if you are using a database to operate your Asterisk + +\end{verbatim} + + +\section{ODBC\_ANTIGF} +\subsection{Syntax} +\begin{verbatim} +ODBC_ANTIGF(<arg1>[...[,<argN>]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Runs the referenced query with the specified arguments +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Runs the following query, as defined in func_odbc.conf, performing +substitution of the arguments into the query as specified by ${ARG1}, +${ARG2}, ... ${ARGn}. This function may only be read, not set. + +SQL: +SELECT COUNT(*) FROM exgirlfriends WHERE callerid='${SQL_ESC(${ARG1})}' + +\end{verbatim} + + +\section{ODBC\_FETCH} +\subsection{Syntax} +\begin{verbatim} +ODBC_FETCH(<result-id>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Fetch a row from a multirow query +\end{verbatim} +\subsection{Description} +\begin{verbatim} +For queries which are marked as mode=multirow, the original query returns a +result-id from which results may be fetched. This function implements the +actual fetch of the results. + +\end{verbatim} + + +\section{ODBC\_PRESENCE} +\subsection{Syntax} +\begin{verbatim} +ODBC_PRESENCE(<arg1>[...[,<argN>]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Runs the referenced query with the specified arguments +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Runs the following query, as defined in func_odbc.conf, performing +substitution of the arguments into the query as specified by ${ARG1}, +${ARG2}, ... ${ARGn}. When setting the function, the values are provided +either in whole as ${VALUE} or parsed as ${VAL1}, ${VAL2}, ... ${VALn}. + +Read: +SELECT location FROM presence WHERE id='${SQL_ESC(${ARG1})}' + +Write: +UPDATE presence SET location='${SQL_ESC(${VAL1})}' WHERE id='${SQL_ESC(${ARG1})}' + +\end{verbatim} + + +\section{ODBC\_SQL} +\subsection{Syntax} +\begin{verbatim} +ODBC_SQL(<arg1>[...[,<argN>]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Runs the referenced query with the specified arguments +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Runs the following query, as defined in func_odbc.conf, performing +substitution of the arguments into the query as specified by ${ARG1}, +${ARG2}, ... ${ARGn}. This function may only be read, not set. + +SQL: +${ARG1} + +\end{verbatim} + + +\section{QUEUE\_MEMBER\_COUNT} +\subsection{Syntax} +\begin{verbatim} +QUEUE_MEMBER_COUNT(<queuename>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Count number of members answering a queue +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns the number of members currently associated with the specified queue. + +\end{verbatim} + + +\section{QUEUE\_MEMBER\_LIST} +\subsection{Syntax} +\begin{verbatim} +QUEUE_MEMBER_LIST(<queuename>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Returns a list of interfaces on a queue +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns a comma-separated list of members associated with the specified queue. + +\end{verbatim} + + +\section{QUEUE\_VARIABLES} +\subsection{Syntax} +\begin{verbatim} +QUEUE_VARIABLES(<queuename>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Return Queue information in variables +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Makes the following queue variables available. +QUEUEMAX maxmimum number of calls allowed +QUEUESTRATEGY the strategy of the queue +QUEUECALLS number of calls currently in the queue +QUEUEHOLDTIME current average hold time +QUEUECOMPLETED number of completed calls for the queue +QUEUEABANDONED number of abandoned calls +QUEUESRVLEVEL queue service level +QUEUESRVLEVELPERF current service level performance +Returns 0 if queue is found and setqueuevar is defined, -1 otherwise +\end{verbatim} + + +\section{QUEUE\_WAITING\_COUNT} +\subsection{Syntax} +\begin{verbatim} +QUEUE_WAITING_COUNT(<queuename>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Count number of calls currently waiting in a queue +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns the number of callers currently waiting in the specified queue. + +\end{verbatim} + + +\section{QUOTE} +\subsection{Syntax} +\begin{verbatim} +QUOTE(<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Quotes a given string, escaping embedded quotes as necessary +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{RAND} +\subsection{Syntax} +\begin{verbatim} +RAND([min][|max]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Choose a random number in a range +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Choose a random number between min and max. Min defaults to 0, if not +specified, while max defaults to RAND_MAX (2147483647 on many systems). + Example: Set(junky=${RAND(1|8)}); + Sets junky to a random number between 1 and 8, inclusive. + +\end{verbatim} + + +\section{REALTIME} +\subsection{Syntax} +\begin{verbatim} +REALTIME(family|fieldmatch[|value[|delim1[|delim2]]]) on read +REALTIME(family|fieldmatch|value|field) on write + +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +RealTime Read/Write Functions +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function will read or write values from/to a RealTime repository. +REALTIME(....) will read names/values from the repository, and +REALTIME(....)= will write a new value/field to the repository. On a +read, this function returns a delimited text string. The name/value +pairs are delimited by delim1, and the name and value are delimited +between each other with delim2. The default for delim1 is '|' and +the default for delim2 is '='. If there is no match, NULL will be +returned by the function. On a write, this function will always +return NULL. + +\end{verbatim} + + +\section{REGEX} +\subsection{Syntax} +\begin{verbatim} +REGEX("<regular expression>" <data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Regular Expression +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns 1 if data matches regular expression, or 0 otherwise. +Please note that the space following the double quotes separating the regex from the data +is optional and if present, is skipped. If a space is desired at the beginning of the data, +then put two spaces there; the second will not be skipped. + +\end{verbatim} + + +\section{SET} +\subsection{Syntax} +\begin{verbatim} +SET(<varname>=[<value>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +SET assigns a value to a channel variable +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{SHA1} +\subsection{Syntax} +\begin{verbatim} +SHA1(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Computes a SHA1 digest +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Generate a SHA1 digest via the SHA1 algorythm. + Example: Set(sha1hash=${SHA1(junky)}) + Sets the asterisk variable sha1hash to the string '60fa5675b9303eb62f99a9cd47f9f5837d18f9a0' + which is known as his hash + +\end{verbatim} + + +\section{SHELL} +\subsection{Syntax} +\begin{verbatim} +SHELL(<command>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Executes a command as if you were at a shell. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Returns the value from a system command + Example: Set(foo=${SHELL(echo "bar")}) + Note: When using the SHELL() dialplan function, your "SHELL" is /bin/sh, + which may differ as to the underlying shell, depending upon your production + platform. Also keep in mind that if you are using a common path, you should + be mindful of race conditions that could result from two calls running + SHELL() simultaneously. + +\end{verbatim} + + +\section{SIP\_HEADER} +\subsection{Syntax} +\begin{verbatim} +SIP_HEADER(<name>[,<number>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets the specified SIP header +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Since there are several headers (such as Via) which can occur multiple +times, SIP_HEADER takes an optional second argument to specify which header with +that name to retrieve. Headers start at offset 1. + +\end{verbatim} + + +\section{SIPCHANINFO} +\subsection{Syntax} +\begin{verbatim} +SIPCHANINFO(item) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets the specified SIP parameter from the current channel +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Valid items are: +- peerip The IP address of the peer. +- recvip The source IP address of the peer. +- from The URI from the From: header. +- uri The URI from the Contact: header. +- useragent The useragent. +- peername The name of the peer. +- t38passthrough 1 if T38 is offered or enabled in this channel, otherwise 0 + +\end{verbatim} + + +\section{SIPPEER} +\subsection{Syntax} +\begin{verbatim} +SIPPEER(<peername>[|item]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets SIP peer information +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Valid items are: +- ip (default) The IP address. +- port The port number +- mailbox The configured mailbox. +- context The configured context. +- expire The epoch time of the next expire. +- dynamic Is it dynamic? (yes/no). +- callerid_name The configured Caller ID name. +- callerid_num The configured Caller ID number. +- callgroup The configured Callgroup. +- pickupgroup The configured Pickupgroup. +- codecs The configured codecs. +- status Status (if qualify=yes). +- regexten Registration extension +- limit Call limit (call-limit) +- curcalls Current amount of calls + Only available if call-limit is set +- language Default language for peer +- accountcode Account code for this peer +- useragent Current user agent id for peer +- codec[x] Preferred codec index number 'x' (beginning with zero). + + +\end{verbatim} + + +\section{SORT} +\subsection{Syntax} +\begin{verbatim} +SORT(key1:val1[...][,keyN:valN]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Sorts a list of key/vals into a list of keys, based upon the vals +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Takes a comma-separated list of keys and values, each separated by a colon, and returns a +comma-separated list of the keys, sorted by their values. Values will be evaluated as +floating-point numbers. + +\end{verbatim} + + +\section{SPEECH} +\subsection{Syntax} +\begin{verbatim} +SPEECH(argument) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets information about speech recognition results. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets information about speech recognition results. +status: Returns 1 upon speech object existing, or 0 if not +spoke: Returns 1 if spoker spoke, or 0 if not +results: Returns number of results that were recognized + +\end{verbatim} + + +\section{SPEECH\_ENGINE} +\subsection{Syntax} +\begin{verbatim} +SPEECH_ENGINE(name)=value +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Change a speech engine specific attribute. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Changes a speech engine specific attribute. + +\end{verbatim} + + +\section{SPEECH\_GRAMMAR} +\subsection{Syntax} +\begin{verbatim} +SPEECH_GRAMMAR([nbest number/]result number) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets the matched grammar of a result if available. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets the matched grammar of a result if available. + +\end{verbatim} + + +\section{SPEECH\_RESULTS\_TYPE} +\subsection{Syntax} +\begin{verbatim} +SPEECH_RESULTS_TYPE()=results type +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Sets the type of results that will be returned. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Sets the type of results that will be returned. Valid options are normal or nbest. +\end{verbatim} + + +\section{SPEECH\_SCORE} +\subsection{Syntax} +\begin{verbatim} +SPEECH_SCORE([nbest number/]result number) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets the confidence score of a result. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets the confidence score of a result. + +\end{verbatim} + + +\section{SPEECH\_TEXT} +\subsection{Syntax} +\begin{verbatim} +SPEECH_TEXT([nbest number/]result number) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets the recognized text of a result. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets the recognized text of a result. + +\end{verbatim} + + +\section{SPRINTF} +\subsection{Syntax} +\begin{verbatim} +SPRINTF(<format>|<arg1>[|...<argN>]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Format a variable according to a format string +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Parses the format string specified and returns a string matching that format. +Supports most options supported by sprintf(3). Returns a shortened string if +a format specifier is not recognized. + +\end{verbatim} + + +\section{SQL\_ESC} +\subsection{Syntax} +\begin{verbatim} +SQL_ESC(<string>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Escapes single ticks for use in SQL statements +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Used in SQL templates to escape data which may contain single ticks (') which +are otherwise used to delimit data. For example: +SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}' + +\end{verbatim} + + +\section{STAT} +\subsection{Syntax} +\begin{verbatim} +STAT(<flag>,<filename>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Does a check on the specified file +\end{verbatim} +\subsection{Description} +\begin{verbatim} +flag may be one of the following: + d - Checks if the file is a directory + e - Checks if the file exists + f - Checks if the file is a regular file + m - Returns the file mode (in octal) + s - Returns the size (in bytes) of the file + A - Returns the epoch at which the file was last accessed + C - Returns the epoch at which the inode was last changed + M - Returns the epoch at which the file was last modified + +\end{verbatim} + + +\section{STRFTIME} +\subsection{Syntax} +\begin{verbatim} +STRFTIME([<epoch>][|[timezone][|format]]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Returns the current date/time in a specified format. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{STRPTIME} +\subsection{Syntax} +\begin{verbatim} +STRPTIME(<datetime>|<timezone>|<format>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Returns the epoch of the arbitrary date/time string structured as described in the format. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This is useful for converting a date into an EPOCH time, possibly to pass to +an application like SayUnixTime or to calculate the difference between two +date strings. + +Example: + ${STRPTIME(2006-03-01 07:30:35|America/Chicago|%Y-%m-%d %H:%M:%S)} returns 1141219835 + +\end{verbatim} + + +\section{TIMEOUT} +\subsection{Syntax} +\begin{verbatim} +TIMEOUT(timeouttype) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Gets or sets timeouts on the channel. Timeout values are in seconds. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Gets or sets various channel timeouts. The timeouts that can be +manipulated are: + +absolute: The absolute maximum amount of time permitted for a call. A + setting of 0 disables the timeout. + +digit: The maximum amount of time permitted between digits when the + user is typing in an extension. When this timeout expires, + after the user has started to type in an extension, the + extension will be considered complete, and will be + interpreted. Note that if an extension typed in is valid, + it will not have to timeout to be tested, so typically at + the expiry of this timeout, the extension will be considered + invalid (and thus control would be passed to the 'i' + extension, or if it doesn't exist the call would be + terminated). The default timeout is 5 seconds. + +response: The maximum amount of time permitted after falling through a + series of priorities for a channel in which the user may + begin typing an extension. If the user does not type an + extension in this amount of time, control will pass to the + 't' extension if it exists, and if not the call would be + terminated. The default timeout is 10 seconds. + +\end{verbatim} + + +\section{TXTCIDNAME} +\subsection{Syntax} +\begin{verbatim} +TXTCIDNAME(<number>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +TXTCIDNAME looks up a caller name via DNS +\end{verbatim} +\subsection{Description} +\begin{verbatim} +This function looks up the given phone number in DNS to retrieve +the caller id name. The result will either be blank or be the value +found in the TXT record in DNS. + +\end{verbatim} + + +\section{URIDECODE} +\subsection{Syntax} +\begin{verbatim} +URIDECODE(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Decodes a URI-encoded string according to RFC 2396. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{URIENCODE} +\subsection{Syntax} +\begin{verbatim} +URIENCODE(<data>) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Encodes a string to URI-safe encoding according to RFC 2396. +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{VERSION} +\subsection{Syntax} +\begin{verbatim} +VERSION([info]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Return the Version info for this Asterisk +\end{verbatim} +\subsection{Description} +\begin{verbatim} +If there are no arguments, return the version of Asterisk in this format: SVN-branch-1.4-r44830M +If the argument is 'ASTERISK_VERSION_NUM', a string of digits is returned (right now fixed at 999999). +If the argument is 'BUILD_USER', the string representing the user's name whose account was used to configure Asterisk, is returned. +If the argument is 'BUILD_HOSTNAME', the string representing the name of the host on which Asterisk was configured, is returned. +If the argument is 'BUILD_MACHINE', the string representing the type of machine on which Asterisk was configured, is returned. +If the argument is 'BUILD_OS', the string representing the OS of the machine on which Asterisk was configured, is returned. +If the argument is 'BUILD_DATE', the string representing the date on which Asterisk was configured, is returned. +If the argument is 'BUILD_KERNEL', the string representing the kernel version of the machine on which Asterisk was configured, is returned . + Example: Set(junky=${VERSION()}; + Sets junky to the string 'SVN-branch-1.6-r74830M', or possibly, 'SVN-trunk-r45126M'. + +\end{verbatim} + + +\section{VMCOUNT} +\subsection{Syntax} +\begin{verbatim} +VMCOUNT(vmbox[@context][|folder]) +\end{verbatim} +\subsection{Synopsis} +\begin{verbatim} +Counts the voicemail in a specified mailbox +\end{verbatim} +\subsection{Description} +\begin{verbatim} + context - defaults to "default" + folder - defaults to "INBOX" + +\end{verbatim} + + diff --git a/doc/tex/ast_manager_actiondocs.tex b/doc/tex/ast_manager_actiondocs.tex new file mode 100644 index 000000000..4c08c2055 --- /dev/null +++ b/doc/tex/ast_manager_actiondocs.tex @@ -0,0 +1,1144 @@ +% This file is automatically generated by the "manager dump actiondocs" CLI command. Any manual edits will be lost. +\section{AbsoluteTimeout} +\subsection{Synopsis} +\begin{verbatim} +Set Absolute Timeout +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Hangup a channel after a certain time. +Variables: (Names marked with * are required) + *Channel: Channel name to hangup + *Timeout: Maximum duration of the call (sec) +Acknowledges set time with 'Timeout Set' message + +\end{verbatim} + + +\section{AgentLogoff} +\subsection{Synopsis} +\begin{verbatim} +Sets an agent as no longer logged in +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Sets an agent as no longer logged in. +Variables: (Names marked with * are required) + *Agent: Agent ID of the agent to log off + Soft: Set to 'true' to not hangup existing calls + +\end{verbatim} + + +\section{Agents} +\subsection{Synopsis} +\begin{verbatim} +Lists agents and their status +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Will list info about all possible agents. +Variables: NONE + +\end{verbatim} + + +\section{Bridge} +\subsection{Synopsis} +\begin{verbatim} +Bridge two channels already in the PBX +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +command,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Bridge together two channels already in the PBX +Variables: ( Headers marked with * are required ) + *Channel1: Channel to Bridge to Channel2 + *Channel2: Channel to Bridge to Channel1 + Tone: (Yes|No) Play courtesy tone to Channel 2 + + +\end{verbatim} + + +\section{Challenge} +\subsection{Synopsis} +\begin{verbatim} +Generate Challenge for MD5 Auth +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ChangeMonitor} +\subsection{Synopsis} +\begin{verbatim} +Change monitoring filename of a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: The 'ChangeMonitor' action may be used to change the file + started by a previous 'Monitor' action. The following parameters may + be used to control this: + Channel - Required. Used to specify the channel to record. + File - Required. Is the new name of the file created in the + monitor spool directory. + +\end{verbatim} + + +\section{Command} +\subsection{Synopsis} +\begin{verbatim} +Execute Asterisk CLI Command +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +command,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Run a CLI command. +Variables: (Names marked with * are required) + *Command: Asterisk CLI command to run + ActionID: Optional Action id for message matching. + +\end{verbatim} + + +\section{CoreSettings} +\subsection{Synopsis} +\begin{verbatim} +Show PBX core settings (version etc) +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Query for Core PBX settings. +Variables: (Names marked with * are optional) + *ActionID: ActionID of this transaction + +\end{verbatim} + + +\section{CoreStatus} +\subsection{Synopsis} +\begin{verbatim} +Show PBX core status variables +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Query for Core PBX status. +Variables: (Names marked with * are optional) + *ActionID: ActionID of this transaction + +\end{verbatim} + + +\section{DBDel} +\subsection{Synopsis} +\begin{verbatim} +Delete DB Entry +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{DBDelTree} +\subsection{Synopsis} +\begin{verbatim} +Delete DB Tree +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{DBGet} +\subsection{Synopsis} +\begin{verbatim} +Get DB Entry +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{DBPut} +\subsection{Synopsis} +\begin{verbatim} +Put DB Entry +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{Events} +\subsection{Synopsis} +\begin{verbatim} +Control Event Flow +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Enable/Disable sending of events to this manager + client. +Variables: + EventMask: 'on' if all events should be sent, + 'off' if no events should be sent, + 'system,call,log' to select which flags events should have to be sent. + +\end{verbatim} + + +\section{ExtensionState} +\subsection{Synopsis} +\begin{verbatim} +Check Extension Status +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Report the extension state for given extension. + If the extension has a hint, will use devicestate to check + the status of the device connected to the extension. +Variables: (Names marked with * are required) + *Exten: Extension to check state on + *Context: Context for extension + ActionId: Optional ID for this transaction +Will return an "Extension Status" message. +The response will include the hint for the extension and the status. + +\end{verbatim} + + +\section{GetConfig} +\subsection{Synopsis} +\begin{verbatim} +Retrieve configuration +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +config,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: A 'GetConfig' action will dump the contents of a configuration +file by category and contents. +Variables: + Filename: Configuration filename (e.g. foo.conf) + +\end{verbatim} + + +\section{GetConfigJSON} +\subsection{Synopsis} +\begin{verbatim} +Retrieve configuration (JSON format) +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +config,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: A 'GetConfigJSON' action will dump the contents of a configuration +file by category and contents in JSON format. This only makes sense to be used +using rawman over the HTTP interface. +Variables: + Filename: Configuration filename (e.g. foo.conf) + +\end{verbatim} + + +\section{Getvar} +\subsection{Synopsis} +\begin{verbatim} +Gets a Channel Variable +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Get the value of a global or local channel variable. +Variables: (Names marked with * are required) + Channel: Channel to read variable from + *Variable: Variable name + ActionID: Optional Action id for message matching. + +\end{verbatim} + + +\section{Hangup} +\subsection{Synopsis} +\begin{verbatim} +Hangup Channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Hangup a channel +Variables: + Channel: The channel name to be hungup + +\end{verbatim} + + +\section{IAXnetstats} +\subsection{Synopsis} +\begin{verbatim} +Show IAX Netstats +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{IAXpeers} +\subsection{Synopsis} +\begin{verbatim} +List IAX Peers +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{JabberSend} +\subsection{Synopsis} +\begin{verbatim} +Sends a message to a Jabber Client +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Sends a message to a Jabber Client. +Variables: + Jabber: Client or transport Asterisk uses to connect to JABBER. + ScreenName: User Name to message. + Message: Message to be sent to the buddy + +\end{verbatim} + + +\section{ListCommands} +\subsection{Synopsis} +\begin{verbatim} +List available manager commands +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Returns the action name and synopsis for every + action that is available to the user +Variables: NONE + +\end{verbatim} + + +\section{Login} +\subsection{Synopsis} +\begin{verbatim} +Login Manager +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{Logoff} +\subsection{Synopsis} +\begin{verbatim} +Logoff Manager +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Logoff this manager session +Variables: NONE + +\end{verbatim} + + +\section{MailboxCount} +\subsection{Synopsis} +\begin{verbatim} +Check Mailbox Message Count +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Checks a voicemail account for new messages. +Variables: (Names marked with * are required) + *Mailbox: Full mailbox ID <mailbox>@<vm-context> + ActionID: Optional ActionID for message matching. +Returns number of new and old messages. + Message: Mailbox Message Count + Mailbox: <mailboxid> + NewMessages: <count> + OldMessages: <count> + + +\end{verbatim} + + +\section{MailboxStatus} +\subsection{Synopsis} +\begin{verbatim} +Check Mailbox +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Checks a voicemail account for status. +Variables: (Names marked with * are required) + *Mailbox: Full mailbox ID <mailbox>@<vm-context> + ActionID: Optional ActionID for message matching. +Returns number of messages. + Message: Mailbox Status + Mailbox: <mailboxid> + Waiting: <count> + + +\end{verbatim} + + +\section{MeetmeMute} +\subsection{Synopsis} +\begin{verbatim} +Mute a Meetme user +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{MeetmeUnmute} +\subsection{Synopsis} +\begin{verbatim} +Unmute a Meetme user +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{Monitor} +\subsection{Synopsis} +\begin{verbatim} +Monitor a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: The 'Monitor' action may be used to record the audio on a + specified channel. The following parameters may be used to control + this: + Channel - Required. Used to specify the channel to record. + File - Optional. Is the name of the file created in the + monitor spool directory. Defaults to the same name + as the channel (with slashes replaced with dashes). + Format - Optional. Is the audio recording format. Defaults + to "wav". + Mix - Optional. Boolean parameter as to whether to mix + the input and output channels together after the + recording is finished. + +\end{verbatim} + + +\section{Originate} +\subsection{Synopsis} +\begin{verbatim} +Originate Call +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Generates an outgoing call to a Extension/Context/Priority or + Application/Data +Variables: (Names marked with * are required) + *Channel: Channel name to call + Exten: Extension to use (requires 'Context' and 'Priority') + Context: Context to use (requires 'Exten' and 'Priority') + Priority: Priority to use (requires 'Exten' and 'Context') + Application: Application to use + Data: Data to use (requires 'Application') + Timeout: How long to wait for call to be answered (in ms) + CallerID: Caller ID to be set on the outgoing channel + Variable: Channel variable to set, multiple Variable: headers are allowed + Account: Account code + Async: Set to 'true' for fast origination + +\end{verbatim} + + +\section{Park} +\subsection{Synopsis} +\begin{verbatim} +Park a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Park a channel. +Variables: (Names marked with * are required) + *Channel: Channel name to park + *Channel2: Channel to announce park info to (and return to if timeout) + Timeout: Number of milliseconds to wait before callback. + +\end{verbatim} + + +\section{ParkedCalls} +\subsection{Synopsis} +\begin{verbatim} +List parked calls +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{PauseMonitor} +\subsection{Synopsis} +\begin{verbatim} +Pause monitoring of a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: The 'PauseMonitor' action may be used to temporarily stop the + recording of a channel. The following parameters may + be used to control this: + Channel - Required. Used to specify the channel to record. + +\end{verbatim} + + +\section{Ping} +\subsection{Synopsis} +\begin{verbatim} +Keepalive command +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: A 'Ping' action will ellicit a 'Pong' response. Used to keep the + manager connection open. +Variables: NONE + +\end{verbatim} + + +\section{PlayDTMF} +\subsection{Synopsis} +\begin{verbatim} +Play DTMF signal on a specific channel. +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Plays a dtmf digit on the specified channel. +Variables: (all are required) + Channel: Channel name to send digit to + Digit: The dtmf digit to play + +\end{verbatim} + + +\section{QueueAdd} +\subsection{Synopsis} +\begin{verbatim} +Add interface to queue. +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{QueueLog} +\subsection{Synopsis} +\begin{verbatim} +Adds custom entry in queue_log +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{QueuePause} +\subsection{Synopsis} +\begin{verbatim} +Makes a queue member temporarily unavailable +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{QueueRemove} +\subsection{Synopsis} +\begin{verbatim} +Remove interface from queue. +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +agent,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{Queues} +\subsection{Synopsis} +\begin{verbatim} +Queues +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{QueueStatus} +\subsection{Synopsis} +\begin{verbatim} +Queue Status +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{QueueSummary} +\subsection{Synopsis} +\begin{verbatim} +Queue Summary +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{Redirect} +\subsection{Synopsis} +\begin{verbatim} +Redirect (transfer) a call +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Redirect (transfer) a call. +Variables: (Names marked with * are required) + *Channel: Channel to redirect + ExtraChannel: Second call leg to transfer (optional) + *Exten: Extension to transfer to + *Context: Context to transfer to + *Priority: Priority to transfer to + ActionID: Optional Action id for message matching. + +\end{verbatim} + + +\section{SendText} +\subsection{Synopsis} +\begin{verbatim} +Send text message to channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Sends A Text Message while in a call. +Variables: (Names marked with * are required) + *Channel: Channel to send message to + *Message: Message to send + ActionID: Optional Action id for message matching. + +\end{verbatim} + + +\section{Setvar} +\subsection{Synopsis} +\begin{verbatim} +Set Channel Variable +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Set a global or local channel variable. +Variables: (Names marked with * are required) + Channel: Channel to set variable for + *Variable: Variable name + *Value: Value + +\end{verbatim} + + +\section{ShowDialPlan} +\subsection{Synopsis} +\begin{verbatim} +List dialplan +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +config,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Show dialplan contexts and extensions. +Be aware that showing the full dialplan may take a lot of capacity +Variables: + ActionID: <id> Action ID for this AMI transaction (optional) + Extension: <extension> Extension (Optional) + Context: <context> Context (Optional) + + +\end{verbatim} + + +\section{SIPpeers} +\subsection{Synopsis} +\begin{verbatim} +List SIP peers (text format) +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Lists SIP peers in text format with details on current status. +Peerlist will follow as separate events, followed by a final event called +PeerlistComplete. +Variables: + ActionID: <id> Action ID for this transaction. Will be returned. + +\end{verbatim} + + +\section{SIPshowpeer} +\subsection{Synopsis} +\begin{verbatim} +Show SIP peer (text format) +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +system,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Show one SIP peer with details on current status. +Variables: + Peer: <name> The peer name you want to check. + ActionID: <id> Optional action ID for this AMI transaction. + +\end{verbatim} + + +\section{Status} +\subsection{Synopsis} +\begin{verbatim} +Lists channel status +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{StopMonitor} +\subsection{Synopsis} +\begin{verbatim} +Stop monitoring a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: The 'StopMonitor' action may be used to end a previously + started 'Monitor' action. The only parameter is 'Channel', the name + of the channel monitored. + +\end{verbatim} + + +\section{UnpauseMonitor} +\subsection{Synopsis} +\begin{verbatim} +Unpause monitoring of a channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: The 'UnpauseMonitor' action may be used to re-enable recording + of a channel after calling PauseMonitor. The following parameters may + be used to control this: + Channel - Required. Used to specify the channel to record. + +\end{verbatim} + + +\section{UpdateConfig} +\subsection{Synopsis} +\begin{verbatim} +Update basic configuration +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +config,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: A 'UpdateConfig' action will dump the contents of a configuration +file by category and contents. +Variables (X's represent 6 digit number beginning with 000000): + SrcFilename: Configuration filename to read(e.g. foo.conf) + DstFilename: Configuration filename to write(e.g. foo.conf) + Reload: Whether or not a reload should take place (or name of specific module) + Action-XXXXXX: Action to Take (NewCat,RenameCat,DelCat,Update,Delete,Append) + Cat-XXXXXX: Category to operate on + Var-XXXXXX: Variable to work on + Value-XXXXXX: Value to work on + Match-XXXXXX: Extra match required to match line + +\end{verbatim} + + +\section{UserEvent} +\subsection{Synopsis} +\begin{verbatim} +Send an arbitrary event +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +user,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: Send an event to manager sessions. +Variables: (Names marked with * are required) + *UserEvent: EventStringToSend + Header1: Content1 + HeaderN: ContentN + +\end{verbatim} + + +\section{VoicemailUsersList} +\subsection{Synopsis} +\begin{verbatim} +List All Voicemail User Information +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +call,all +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{WaitEvent} +\subsection{Synopsis} +\begin{verbatim} +Wait for an event to occur +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +Description: A 'WaitEvent' action will ellicit a 'Success' response. Whenever +a manager event is queued. Once WaitEvent has been called on an HTTP manager +session, events will be generated and queued. +Variables: + Timeout: Maximum time (in seconds) to wait for events, -1 means forever. + +\end{verbatim} + + +\section{ZapDialOffhook} +\subsection{Synopsis} +\begin{verbatim} +Dial over Zap channel while offhook +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapDNDoff} +\subsection{Synopsis} +\begin{verbatim} +Toggle Zap channel Do Not Disturb status OFF +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapDNDon} +\subsection{Synopsis} +\begin{verbatim} +Toggle Zap channel Do Not Disturb status ON +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapHangup} +\subsection{Synopsis} +\begin{verbatim} +Hangup Zap Channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapRestart} +\subsection{Synopsis} +\begin{verbatim} +Fully Restart zaptel channels (terminates calls) +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapShowChannels} +\subsection{Synopsis} +\begin{verbatim} +Show status zapata channels +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + +\section{ZapTransfer} +\subsection{Synopsis} +\begin{verbatim} +Transfer Zap Channel +\end{verbatim} +\subsection{Authority} +\begin{verbatim} +<none> +\end{verbatim} +\subsection{Description} +\begin{verbatim} +(null) +\end{verbatim} + + diff --git a/doc/tex/asterisk-conf.tex b/doc/tex/asterisk-conf.tex new file mode 100644 index 000000000..119a1cc24 --- /dev/null +++ b/doc/tex/asterisk-conf.tex @@ -0,0 +1,133 @@ +\subsubsection{Asterisk Main Configuration File} + +Below is a sample of the main Asterisk configuration file, +asterisk.conf. Note that this file is not provided in +sample form, because the Makefile creates it when needed +and does not touch it when it already exists. + +\begin{verbatim} +[directories] +; Make sure these directories have the right permissions if not +; running Asterisk as root + +; Where the configuration files (except for this one) are located +astetcdir => /etc/asterisk + +; Where the Asterisk loadable modules are located +astmoddir => /usr/lib/asterisk/modules + +; Where additional 'library' elements (scripts, etc.) are located +astvarlibdir => /var/lib/asterisk + +; Where AGI scripts/programs are located +astagidir => /var/lib/asterisk/agi-bin + +; Where spool directories are located +; Voicemail, monitor, dictation and other apps will create files here +; and outgoing call files (used with pbx_spool) must be placed here +astspooldir => /var/spool/asterisk + +; Where the Asterisk process ID (pid) file should be created +astrundir => /var/run/asterisk + +; Where the Asterisk log files should be created +astlogdir => /var/log/asterisk + + +[options] +;Under "options" you can enter configuration options +;that you also can set with command line options + +; Verbosity level for logging (-v) +verbose = 0 + +; Debug: "No" or value (1-4) +debug = 3 + +; Background execution disabled (-f) +nofork=yes | no + +; Always background, even with -v or -d (-F) +alwaysfork=yes | no + +; Console mode (-c) +console= yes | no + +; Execute with high priority (-p) +highpriority = yes | no + +; Initialize crypto at startup (-i) +initcrypto = yes | no + +; Disable ANSI colors (-n) +nocolor = yes | no + +; Dump core on failure (-g) +dumpcore = yes | no + +; Run quietly (-q) +quiet = yes | no + +; Force timestamping in CLI verbose output (-T) +timestamp = yes | no + +; User to run asterisk as (-U) NOTE: will require changes to +; directory and device permissions +runuser = asterisk + +; Group to run asterisk as (-G) +rungroup = asterisk + +; Enable internal timing support (-I) +internal_timing = yes | no + +; These options have no command line equivalent + +; Cache record() files in another directory until completion +cache_record_files = yes | no +record_cache_dir = <dir> + +; Build transcode paths via SLINEAR +transcode_via_sln = yes | no + +; send SLINEAR silence while channel is being recorded +transmit_silence_during_record = yes | no + +; The maximum load average we accept calls for +maxload = 1.0 + +; The maximum number of concurrent calls you want to allow +maxcalls = 255 + +; Stop accepting calls when free memory falls below this amount specified in MB +minmemfree = 256 + +; Allow #exec entries in configuration files +execincludes = yes | no + +; Don't over-inform the Asterisk sysadm, he's a guru +dontwarn = yes | no + +; System name. Used to prefix CDR uniqueid and to fill \${SYSTEMNAME} +systemname = <a_string> + +; Should language code be last component of sound file name or first? +; when off, sound files are searched as <path>/<lang>/<file> +; when on, sound files are search as <lang>/<path>/<file> +; (only affects relative paths for sound files) +languageprefix = yes | no + + +[files] +; Changing the following lines may compromise your security +; Asterisk.ctl is the pipe that is used to connect the remote CLI +; (asterisk -r) to Asterisk. Changing these settings change the +; permissions and ownership of this file. +; The file is created when Asterisk starts, in the "astrundir" above. + +;astctlpermissions = 0660 +;astctlowner = root +;astctlgroup = asterisk +;astctl = asterisk.ctl + +\end{verbatim} diff --git a/doc/tex/asterisk.tex b/doc/tex/asterisk.tex new file mode 100644 index 000000000..e6bbf3820 --- /dev/null +++ b/doc/tex/asterisk.tex @@ -0,0 +1,154 @@ +% To generate a PDF from this, install the "rubber" tool, and the LaTeX +% dependencies for it. Then, run: +% +% rubber asterisk.tex +% +% http://www.pps.jussieu.fr/~beffara/soft/rubber/ + +\documentclass[12pt,a4]{report} +\usepackage{hyperref} + +\author{Asterisk Development Team \\ Asterisk.org} +\title{Asterisk Reference Information \\ Version SVN-trunk-r72921M} + +\begin{document} +\maketitle + +\tableofcontents + +\chapter{Introduction} + +This document contains various pieces of information that are useful for +reference purposes. + + \section{License Information} + \input{../../LICENSE} + \subsection{Hold Music} + Digium has licensed the music included with + the Asterisk distribution From FreePlayMusic + for use and distribution with Asterisk. It + is licensed ONLY for use as hold music within + an Asterisk based PBX. + \section{Security} + \input{security.tex} + \section{Hardware} + \input{hardware.tex} + +\chapter{Configuration} + \section{General Configuration Information} + \subsection{Configuration Parser} + \input{configuration.tex} + \subsection{Asterisk.conf} + \input{asterisk-conf.tex} + \subsection{CLI Prompt} + \input{cliprompt.tex} + \subsection{Extensions} + \input{extensions.tex} + \subsection{IP Quality of Service} + \input{qos.tex} + \subsection{MP3 Support} + \input{mp3.tex} + \subsection{ICES} + \input{ices.tex} + \section{Database Support} + \subsection{Realtime Database Configuration} + \input{realtime.tex} + \subsection{FreeTDS} + \input{freetds.tex} + \section{Privacy} + \input{privacy.tex} + +\chapter{Channel Variables} +\input{channelvariables.tex} + +\chapter{AEL, Asterisk Extension Language} +\input{ael.tex} + +\chapter{SLA (Shared Line Appearances)} +\input{sla.tex} + +\chapter{Channel Drivers} + \section{IAX2} + \input{chaniax.tex} + \subsection{IAX2 Jitterbuffer} + \input{jitterbuffer.tex} + \section{mISDN} + \input{misdn.tex} + \section{Local} + \input{localchannel.tex} + +\chapter{Distributed Universal Number Discovery (DUNDi)} + \section{Introduction} + \input{dundi.tex} + \section{Peering Agreement} + \input{../PEERING} + +\chapter{ENUM} +\input{enum.tex} + +\chapter{AMI: Asterisk Manager Interface} + \input{manager.tex} + \input{ajam.tex} + +\chapter{CDR: Call Detail Records} +\input{billing.tex} +\input{cdrdriver.tex} + +\chapter{Voicemail} + \section{ODBC Storage} + \input{odbcstorage.tex} + \section{IMAP Storage} + \input{imapstorage.tex} + +\chapter{SMS} +\input{app-sms.tex} + +\chapter{Queues} + \input{queues-with-callback-members.tex} + \section{Queue Logs} + \input{queuelog.tex} + +% Generate this using the "core dump clidocs" CLI command that is present +% when Asterisk is built with dev-mode enabled. +\chapter{CLI Command Reference} +\input{ast_cli_commands.tex} + +% Generate this using the "core dump appdocs" CLI command that is present +% when Asterisk is built with dev-mode enabled. +\chapter{Dialplan Application Reference} +\input{ast_appdocs.tex} + +% Generate this using the "core dump funcdocs" CLI command that is present +% when Asterisk is built with dev-mode enabled. +\chapter{Dialplan Function Reference} +\input{ast_funcdocs.tex} + +% Generate this using the "manager dump actiondocs" CLI command that is present +% when Asterisk is built with dev-mode enabled. +\chapter{Manager Action Reference} +\input{ast_manager_actiondocs.tex} + +% Generate this using the "agi dump commanddocs" CLI command that is present +% when Asterisk is built with dev-mode enabled. +\chapter{AGI Command Reference} +\input{ast_agi_commands.tex} + +% This is a list of files not yet integrated into this document: +% +%Misc +%---- +%asterisk-mib.txt SNMP mib for Asterisk (net-snmp) +%digium-mib.txt SNMP mib for Asterisk (net-snmp) +% +%For developers +%-------------- +%See http://www.asterisk.org/developers for more information +% +%backtrace.txt How to produce a backtrace when Asterisk crashes +%CODING-GUIDELINES Guidelines for developers +%externalivr.txt Documentation of the protocol used in externalivr() +%modules.txt How Asterisk modules work +%datastores.txt About channel data stores +%speechrec.txt The Generic Speech Recognition API + +\enddocument diff --git a/doc/tex/billing.tex b/doc/tex/billing.tex new file mode 100644 index 000000000..e1d3131fa --- /dev/null +++ b/doc/tex/billing.tex @@ -0,0 +1,87 @@ +\section{Applications} + +\begin{itemize} + \item SetAccount - Set account code for billing + \item SetAMAFlags - Sets AMA flags + \item NoCDR - Make sure no CDR is saved for a specific call + \item ResetCDR - Reset CDR + \item ForkCDR - Save current CDR and start a new CDR for this call + \item Authenticate - Authenticates and sets the account code + \item SetCDRUserField - Set CDR user field + \item AppendCDRUserField - Append data to CDR User field +\end{itemize} + +For more information, use the "core show application <application>" command. +You can set default account codes and AMA flags for devices in +channel configuration files, like sip.conf, iax.conf etc. + + +\section{Fields of the CDR in Asterisk} + +\begin{itemize} + \item accountcode: What account number to use, (string, 20 characters) + \item src: Caller*ID number (string, 80 characters) + \item dst: Destination extension (string, 80 characters) + \item dcontext: Destination context (string, 80 characters) + \item clid: Caller*ID with text (80 characters) + \item channel: Channel used (80 characters) + \item dstchannel: Destination channel if appropriate (80 characters) + \item lastapp: Last application if appropriate (80 characters) + \item lastdata: Last application data (arguments) (80 characters) + \item start: Start of call (date/time) + \item answer: Answer of call (date/time) + \item end: End of call (date/time) + \item duration: Total time in system, in seconds (integer), from dial to hangup + \item billsec: Total time call is up, in seconds (integer), from answer to hangup + \item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY + \item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc, + specified on a per channel basis like accountcode. + \item user field: A user-defined field, maximum 255 characters +\end{itemize} + +In some cases, uniqueid is appended: + +\begin{itemize} + \item uniqueid: Unique Channel Identifier (32 characters) + This needs to be enabled in the source code at compile time +\end{itemize} + +NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers +(not media-only transfers), then when the calls is transferred the server +in the middle will no longer be involved in the signaling path, and thus +will not generate accurate CDRs for that call. If you can, use media-only +transfers with IAX2 to avoid this problem, or turn off transfers completely +(although this can result in a media latency increase since the media packets +have to traverse the middle server(s) in the call). + +\section{CDR Variables} + +If the channel has a cdr, that cdr record has its own set of variables which +can be accessed just like channel variables. The following builtin variables +are available. + +\begin{verbatim} +${CDR(clid)} Caller ID +${CDR(src)} Source +${CDR(dst)} Destination +${CDR(dcontext)} Destination context +${CDR(channel)} Channel name +${CDR(dstchannel)} Destination channel +${CDR(lastapp)} Last app executed +${CDR(lastdata)} Last app's arguments +${CDR(start)} Time the call started. +${CDR(answer)} Time the call was answered. +${CDR(end)} Time the call ended. +${CDR(duration)} Duration of the call. +${CDR(billsec)} Duration of the call once it was answered. +${CDR(disposition)} ANSWERED, NO ANSWER, BUSY +${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc +${CDR(accountcode)} The channel's account code. +${CDR(uniqueid)} The channel's unique id. +${CDR(userfield)} The channels uses specified field. +\end{verbatim} + +In addition, you can set your own extra variables by using Set(CDR(name)=value). +These variables can be output into a text-format CDR by using the cdr\_custom +CDR driver; see the cdr\_custom.conf.sample file in the configs directory for +an example of how to do this. diff --git a/doc/tex/cdrdriver.tex b/doc/tex/cdrdriver.tex new file mode 100644 index 000000000..00c99daea --- /dev/null +++ b/doc/tex/cdrdriver.tex @@ -0,0 +1,431 @@ +Call data records can be stored in many different databases or even CSV text. + +\section{MSSQL} + + Asterisk can currently store CDRs into an MSSQL database in + two different ways: cdr\_odbc or cdr\_tds + + Call Data Records can be stored using unixODBC (which requires + the FreeTDS package) [cdr\_odbc] or directly by using just the + FreeTDS package [cdr\_tds] The following provide some + examples known to get asterisk working with mssql. + + NOTE: Only choose one db connector. + +\subsection{ODBC using cdr\_odbc} + Compile, configure, and install the latest unixODBC package: +\begin{verbatim} + tar -zxvf unixODBC-2.2.9.tar.gz && + cd unixODBC-2.2.9 && + ./configure --sysconfdir=/etc --prefix=/usr --disable-gui && + make && + make install +\end{verbatim} + + Compile, configure, and install the latest FreeTDS package: +\begin{verbatim} + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 \ + --with-unixodbc=/usr/lib && + make && make install +\end{verbatim} + + Compile, or recompile, asterisk so that it will now add support + for cdr\_odbc. +\begin{verbatim} + make clean && ./configure --with-odbc && + make update && + make && + make install +\end{verbatim} + + Setup odbc configuration files. These are working examples + from my system. You will need to modify for your setup. + You are not required to store usernames or passwords here. + +\begin{verbatim} + /etc/odbcinst.ini + [FreeTDS] + Description = FreeTDS ODBC driver for MSSQL + Driver = /usr/lib/libtdsodbc.so + Setup = /usr/lib/libtdsS.so + FileUsage = 1 + + /etc/odbc.ini + [MSSQL-asterisk] + description = Asterisk ODBC for MSSQL + driver = FreeTDS + server = 192.168.1.25 + port = 1433 + database = voipdb + tds_version = 7.0 + language = us_english +\end{verbatim} + + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). + This command will erase the contents of cdr\_tds.conf +\begin{verbatim} + [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf +\end{verbatim} + NOTE: unixODBC requires the freeTDS package, but asterisk does + not call freeTDS directly. + + Now set up cdr\_odbc configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. +\begin{verbatim} + /etc/asterisk/cdr_odbc.conf + [global] + dsn=MSSQL-asterisk + username=voipdbuser + password=voipdbpass + loguniqueid=yes +\end{verbatim} + And finally, create the 'cdr' table in your mssql database. +\begin{verbatim} + CREATE TABLE cdr ( + [calldate] [datetime] NOT NULL , + [clid] [varchar] (80) NOT NULL , + [src] [varchar] (80) NOT NULL , + [dst] [varchar] (80) NOT NULL , + [dcontext] [varchar] (80) NOT NULL , + [channel] [varchar] (80) NOT NULL , + [dstchannel] [varchar] (80) NOT NULL , + [lastapp] [varchar] (80) NOT NULL , + [lastdata] [varchar] (80) NOT NULL , + [duration] [int] NOT NULL , + [billsec] [int] NOT NULL , + [disposition] [varchar] (45) NOT NULL , + [amaflags] [int] NOT NULL , + [accountcode] [varchar] (20) NOT NULL , + [uniqueid] [varchar] (32) NOT NULL , + [userfield] [varchar] (255) NOT NULL + ) +\end{verbatim} + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + +\subsection{TDS, using cdr\_tds} + Compile, configure, and install the latest FreeTDS package: +\begin{verbatim} + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 + make && + make install +\end{verbatim} + Compile, or recompile, asterisk so that it will now add support + for cdr\_tds. +\begin{verbatim} + make clean && ./configure --with-tds && + make update && + make && + make install +\end{verbatim} + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). + This command will erase the contents of cdr\_odbc.conf +\begin{verbatim} + [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf +\end{verbatim} + Setup cdr\_tds configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. +\begin{verbatim} + /etc/asterisk/cdr_tds.conf + [global] + hostname=192.168.1.25 + port=1433 + dbname=voipdb + user=voipdbuser + password=voipdpass + charset=BIG5 +\end{verbatim} + And finally, create the 'cdr' table in your mssql database. +\begin{verbatim} + CREATE TABLE cdr ( + [accountcode] [varchar] (20) NULL , + [src] [varchar] (80) NULL , + [dst] [varchar] (80) NULL , + [dcontext] [varchar] (80) NULL , + [clid] [varchar] (80) NULL , + [channel] [varchar] (80) NULL , + [dstchannel] [varchar] (80) NULL , + [lastapp] [varchar] (80) NULL , + [lastdata] [varchar] (80) NULL , + [start] [datetime] NULL , + [answer] [datetime] NULL , + [end] [datetime] NULL , + [duration] [int] NULL , + [billsec] [int] NULL , + [disposition] [varchar] (20) NULL , + [amaflags] [varchar] (16) NULL , + [uniqueid] [varchar] (32) NULL + ) +\end{verbatim} + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + + +\section{MYSQL} + +Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. + +\section{PGSQL} + If you want to go directly to postgresql database, and have the cdr\_pgsql.so + compiled you can use the following sample setup. + On Debian, before compiling asterisk, just install libpqxx-dev. + Other distros will likely have a similiar package. + + Once you have the compile done, + copy the sample cdr\_pgsql.conf file or create your own. + + Here is a sample: +\begin{verbatim} + /etc/asterisk/cdr_pgsql.conf + ; Sample Asterisk config file for CDR logging to PostgresSQL + [global] + hostname=localhost + port=5432 + dbname=asterisk + password=password + user=postgres + table=cdr +\end{verbatim} + Now create a table in postgresql for your cdrs + +\begin{verbatim} + CREATE TABLE cdr ( + calldate time NOT NULL , + clid varchar (80) NOT NULL , + src varchar (80) NOT NULL , + dst varchar (80) NOT NULL , + dcontext varchar (80) NOT NULL , + channel varchar (80) NOT NULL , + dstchannel varchar (80) NOT NULL , + lastapp varchar (80) NOT NULL , + lastdata varchar (80) NOT NULL , + duration int NOT NULL , + billsec int NOT NULL , + disposition varchar (45) NOT NULL , + amaflags int NOT NULL , + accountcode varchar (20) NOT NULL , + uniqueid varchar (32) NOT NULL , + userfield varchar (255) NOT NULL + ); +\end{verbatim} + +\section{SQLLITE} + +SQLite version 2 is supported in cdr\_sqlite. + +\section{RADIUS} + +\subsection{What is needed} + +\begin{itemize} + \item FreeRADIUS server + \item Radiusclient-ng library + \item Asterisk PBX +\end{itemize} + +\begin{verbatim} + +--------------------+ + | Asterisk PBX | + | | + |********************| + | | +---------------+ + | RADIUS client |------->| RADIUS server | + | |<-------| (FreeRADIUS) | + +--------------------+ +---------------+ +\end{verbatim} + + + +\subsection{Steps to follow in order to have RADIUS support} + +\subsubsection{Installation of the Radiusclient library} + Installation: +\begin{verbatim} + Download the sources from: + + http://developer.berlios.de/projects/radiusclient-ng/ + + Untar the source tarball. + root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz + + Compile and install the library. + root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2 + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install +\end{verbatim} + +\subsubsection{Configuration of the Radiusclient library} + + By default all the configuration files of the radiusclient library will + be in /usr/local/etc/radiusclient-ng directory. + + File "radiusclient.conf" + Open the file and find lines containing the following: + + authserver localhost + + This is the hostname or IP address of the RADIUS server used for + authentication. You will have to change this unless the server is + running on the same host as your Asterisk PBX. + + acctserver localhost + This is the hostname or IP address of the RADIUS server used for + accounting. You will have to change this unless the server is running + on the same host as your Asterisk PBX. + + File "servers" + + RADIUS protocol uses simple access control mechanism based on shared + secrets that allows RADIUS servers to limit access from RADIUS clients. + + A RADIUS server is configured with a secret string and only RADIUS + clients that have the same secret will be accepted. + + You need to configure a shared secret for each server you have + configured in radiusclient.conf file in the previous step. The shared + secrets are stored in /usr/local/etc/radiusclient-ng/servers file. + + Each line contains hostname of a RADIUS server and shared secret + used in communication with that server. The two values are separated + by white spaces. Configure shared secrets for every RADIUS server you + are going to use. + + File "dictionary" + + Asterisk uses some attributes that are not included in the + dictionary of radiusclient library, therefore it is necessary to add + them. A file called dictionary.digium (kept in the contrib dir) + was created to list all new attributes used by Asterisk. + Add to the end of the main dictionary file + /usr/local/etc/radiusclient-ng/dictionary + the line: +\begin{verbatim} + \$INCLUDE /path/to/dictionary.digium +\end{verbatim} + +\subsubsection{Install FreeRADIUS Server (Version 1.1.1)} + + Download sources tarball from: + + http://freeradius.org/ + + Untar, configure, build, and install the server: + +\begin{verbatim} + root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz + root@localhost:/usr/local/src# cd freeradius-1.1.1 + root@localhost"/usr/local/src/freeradius-1.1.1# ./configure + root@localhost"/usr/local/src/freeradius-1.1.1# make + root@localhost"/usr/local/src/freeradius-1.1.1# make install +\end{verbatim} + + All the configuration files of FreeRADIUS server will be in + /usr/local/etc/raddb directory. + + +\subsubsection{Configuration of the FreeRADIUS Server} + + There are several files that have to be modified to configure the + RADIUS server. These are presented next. + + File "clients.conf" + + File /usr/local/etc/raddb/clients.conf contains description of + RADIUS clients that are allowed to use the server. For each of the + clients you need to specify its hostname or IP address and also a + shared secret. The shared secret must be the same string you configured + in radiusclient library. + + Example: +\begin{verbatim} + client myhost { + secret = mysecret + shortname = foo + } +\end{verbatim} + + This fragment allows access from RADIUS clients on "myhost" if they use + "mysecret" as the shared secret. + The file already contains an entry for localhost (127.0.0.1), so if you + are running the RADIUS server on the same host as your Asterisk server, + then modify the existing entry instead, replacing the default password. + + File "dictionary" + + Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. + The following procedure brings the dictionary.digium file to previous versions + of FreeRADIUS. + + File /usr/local/etc/raddb/dictionary contains the dictionary of + FreeRADIUS server. You have to add the same dictionary file + (dictionary.digium), which you added to the dictionary of radiusclient-ng + library. You can include it into the main file, adding the following line at the + end of file '/usr/local/etc/raddb/dictionary': + + \$INCLUDE /path/to/dictionary.digium + + That will include the same new attribute definitions that are used + in radiusclient-ng library so the client and server will understand each + other. + + +\subsubsection{Asterisk Accounting Configuration} + + Compilation and installation: + + The module will be compiled as long as the radiusclient-ng + library has been detected on your system. + + By default FreeRADIUS server will log all accounting requests into + /usr/local/var/log/radius/radacct directory in form of plain text files. + The server will create one file for each hostname in the directory. The + following example shows how the log files look like. + + Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h + for all the fields which are recorded. By default, records in comma + separated values will be created in /var/log/asterisk/cdr-csv. + + The configuration file for cdr\_radius.so module is : + + /etc/asterisk/cdr.conf + This is where you can set CDR related parameters as well as the path to + the radiusclient-ng library configuration file. + + +\section{Logged Values} +\begin{verbatim} + "Asterisk-Acc-Code", The account name of detail records + "Asterisk-Src", + "Asterisk-Dst", + "Asterisk-Dst-Ctx", The destination context + "Asterisk-Clid", + "Asterisk-Chan", The channel + "Asterisk-Dst-Chan", (if applicable) + "Asterisk-Last-App", Last application run on the channel + "Asterisk-Last-Data", Argument to the last channel + "Asterisk-Start-Time", + "Asterisk-Answer-Time", + "Asterisk-End-Time", + "Asterisk-Duration", Duration is the whole length that the entire + call lasted. ie. call rx'd to hangup + "end time" minus "start time" + "Asterisk-Bill-Sec", The duration that a call was up after other + end answered which will be <= to duration + "end time" minus "answer time" + "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY + "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on + a per channel basis like accountcode. + "Asterisk-Unique-ID", Unique call identifier + "Asterisk-User-Field" User field set via SetCDRUserField +\end{verbatim} diff --git a/doc/tex/chaniax.tex b/doc/tex/chaniax.tex new file mode 100644 index 000000000..954e068b0 --- /dev/null +++ b/doc/tex/chaniax.tex @@ -0,0 +1,84 @@ +\subsection{Introduction} + +This section is intended as an introduction to the Inter-Asterisk +eXchange v2 (or simply IAX2) protocol. It provides both a theoretical +background and practical information on its use. + +\subsection{Why IAX2?} + +The first question most people are thinking at this point is "Why do you +need another VoIP protocol? Why didn't you just use SIP or H.323?" + +Well, the answer is a fairly complicated one, but in a nutshell it's like +this... Asterisk is intended as a very flexible and powerful +communications tool. As such, the primary feature we need from a VoIP +protocol is the ability to meet our own goals with Asterisk, and one with +enough flexibility that we could use it as a kind of laboratory for +inventing and implementing new concepts in the field. Neither H.323 or +SIP fit the roles we needed, so we developed our own protocol, which, +while not standards based, provides a number of advantages over both SIP +and H.323, some of which are: + +\begin{itemize} + \item Interoperability with NAT/PAT/Masquerade firewalls + \begin{itemize} + \item IAX seamlessly interoperates through all sorts of NAT and PAT + and other firewalls, including the ability to place and + receive calls, and transfer calls to other stations. + \end{itemize} + \item High performance, low overhead protocol + \begin{itemize} + \item When running on low-bandwidth connections, or when running + large numbers of calls, optimized bandwidth utilization is + imperative. IAX uses only 4 bytes of overhead + \end{itemize} + \item Internationalization support + \begin{itemize} + \item IAX transmits language information, so that remote PBX + content can be delivered in the native language of the + calling party. + \end{itemize} + \item Remote dialplan polling + \begin{itemize} + \item IAX allows a PBX or IP phone to poll the availability of a + number from a remote server. This allows PBX dialplans to + be centralized. + \end{itemize} + \item Flexible authentication + \begin{itemize} + \item IAX supports cleartext, md5, and RSA authentication, + providing flexible security models for outgoing calls and + registration services. + \end{itemize} + \item Multimedia protocol + \begin{itemize} + \item IAX supports the transmission of voice, video, images, text, + HTML, DTMF, and URL's. Voice menus can be presented in both + audibly and visually. + \end{itemize} + \item Call statistic gathering + \begin{itemize} + \item IAX gathers statistics about network performance (including + latency and jitter, as well as providing end-to-end latency + measurement. + \end{itemize} + \item Call parameter communication + \begin{itemize} + \item Caller*ID, requested extension, requested context, etc are + all communicated through the call. + \end{itemize} + \item Single socket design + \begin{itemize} + \item IAX's single socket design allows up to 32768 calls to be + multiplexed. + \end{itemize} +\end{itemize} + +While we value the importance of standards based (i.e. SIP) call handling, +hopefully this will provide a reasonable explanation of why we developed +IAX rather than starting with SIP. + +\subsection{Configuration} + +For examples of a configuration, please see the iax.conf.sample in +your the /configs directory of you source code distribution. diff --git a/doc/tex/channelvariables.tex b/doc/tex/channelvariables.tex new file mode 100644 index 000000000..8b50d0459 --- /dev/null +++ b/doc/tex/channelvariables.tex @@ -0,0 +1,791 @@ +\section{Introduction} + +There are two levels of parameter evaluation done in the Asterisk +dial plan in extensions.conf. +\begin{enumerate} +\item The first, and most frequently used, is the substitution of variable + references with their values. +\item Then there are the evaluations of expressions done in \$[ .. ]. + This will be discussed below. +\end{enumerate} +Asterisk has user-defined variables and standard variables set +by various modules in Asterisk. These standard variables are +listed at the end of this document. + +\section{Parameter Quoting} +\begin{verbatim} +exten => s,5,BackGround,blabla +\end{verbatim} +The parameter (blabla) can be quoted ("blabla"). In this case, a +comma does not terminate the field. However, the double quotes +will be passed down to the Background command, in this example. + +Also, characters special to variable substitution, expression evaluation, etc +(see below), can be quoted. For example, to literally use a \$ on the +string "\$1231", quote it with a preceding \\. Special characters that must +be quoted to be used, are [ ] \$ " \\. (to write \\ itself, use \\). + +These Double quotes and escapes are evaluated at the level of the +asterisk config file parser. + +Double quotes can also be used inside expressions, as discussed below. + +\section{Variables} + +Parameter strings can include variables. Variable names are arbitrary strings. +They are stored in the respective channel structure. + +To set a variable to a particular value, do : +\begin{verbatim} + exten => 1,2,Set(varname=value) +\end{verbatim} +You can substitute the value of a variable everywhere using \${variablename}. +For example, to stringwise append \$lala to \$blabla and store result in \$koko, +do: +\begin{verbatim} + exten => 1,2,Set(koko=${blabla}${lala}) +\end{verbatim} + +There are two reference modes - reference by value and reference by name. +To refer to a variable with its name (as an argument to a function that +requires a variable), just write the name. To refer to the variable's value, +enclose it inside \${}. For example, Set takes as the first argument +(before the =) a variable name, so: +\begin{verbatim} + exten => 1,2,Set(koko=lala) + exten => 1,3,Set(${koko}=blabla) +\end{verbatim} +stores to the variable "koko" the value "lala" and to variable "lala" the +value "blabla". + +In fact, everything contained \${here} is just replaced with the value of +the variable "here". + +\section{Variable Inheritance} + +Variable names which are prefixed by "\_" will be inherited to channels +that are created in the process of servicing the original channel in +which the variable was set. When the inheritance takes place, the +prefix will be removed in the channel inheriting the variable. If the +name is prefixed by "\_\_" in the channel, then the variable is +inherited and the "\_\_" will remain intact in the new channel. + +In the dialplan, all references to these variables refer to the same +variable, regardless of having a prefix or not. Note that setting any +version of the variable removes any other version of the variable, +regardless of prefix. + +\subsection{Example} +\begin{verbatim} +Set(__FOO=bar) ; Sets an inherited version of "FOO" variable +Set(FOO=bar) ; Removes the inherited version and sets a local + ; variable. + +However, + +NoOp(${__FOO}) is identical to NoOp(${FOO}) +\end{verbatim} + + +\section{Selecting Characters from Variables} + +The format for selecting characters from a variable can be expressed as: +\begin{verbatim} + ${variable_name[:offset[:length]]} +\end{verbatim} +If you want to select the first N characters from the string assigned +to a variable, simply append a colon and the number of characters to +skip from the beginning of the string to the variable name. +\begin{verbatim} + ;Remove the first character of extension, save in "number" variable + exten => _9X.,1,Set(number=${EXTEN:1}) +\end{verbatim} +Assuming we've dialed 918005551234, the value saved to the 'number' variable +would be 18005551234. This is useful in situations when we require users to +dial a number to access an outside line, but do not wish to pass the first +digit. + +If you use a negative offset number, Asterisk starts counting from the end +of the string and then selects everything after the new position. The following +example will save the numbers 1234 to the 'number' variable, still assuming +we've dialed 918005551234. +\begin{verbatim} + ;Remove everything before the last four digits of the dialed string + exten => _9X.,1,Set(number=${EXTEN:-4}) +\end{verbatim} +We can also limit the number of characters from our offset position that we +wish to use. This is done by appending a second colon and length value to the +variable name. The following example will save the numbers 555 to the 'number' +variable. +\begin{verbatim} + ;Only save the middle numbers 555 from the string 918005551234 + exten => _9X.,1,Set(number=${EXTEN:5:3}) +\end{verbatim} +The length value can also be used in conjunction with a negative offset. This +may be useful if the length of the string is unknown, but the trailing digits +are. The following example will save the numbers 555 to the 'number' variable, +even if the string starts with more characters than expected (unlike the +previous example). +\begin{verbatim} + ;Save the numbers 555 to the 'number' variable + exten => _9X.,1,Set(number=${EXTEN:-7:3}) +\end{verbatim} +If a negative length value is entered, Asterisk will remove that many characters +from the end of the string. +\begin{verbatim} + ;Set pin to everything but the trailing #. + exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) +\end{verbatim} + +\section{Expressions} + +Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is +considered as an expression and it is evaluated. Evaluation works similar to +(but is done on a later stage than) variable substitution: the expression +(including the square brackets) is replaced by the result of the expression +evaluation. + +For example, after the sequence: +\begin{verbatim} +exten => 1,1,Set(lala=$[1 + 2]) +exten => 1,2,Set(koko=$[2 * ${lala}]) +\end{verbatim} +the value of variable koko is "6". + +and, further: +\begin{verbatim} +exten => 1,1,Set,(lala=$[ 1 + 2 ]); +\end{verbatim} +will parse as intended. Extra spaces are ignored. + + +\subsection{Spaces Inside Variables Values} + +If the variable being evaluated contains spaces, there can be problems. + +For these cases, double quotes around text that may contain spaces +will force the surrounded text to be evaluated as a single token. +The double quotes will be counted as part of that lexical token. + +As an example: + +\begin{verbatim} +exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) +\end{verbatim} + +The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space) +but the above will evaluate to: + +\begin{verbatim} +"DELOREAN MOTORS" : "Privacy Manager" +\end{verbatim} + +and will evaluate to 0. + +The above without double quotes would have evaluated to: + +\begin{verbatim} +DELOREAN MOTORS : Privacy Manager +\end{verbatim} + +and will result in syntax errors, because token DELOREAN is immediately +followed by token MOTORS and the expression parser will not know how to +evaluate this expression, because it does not match its grammar. + +\subsection{Operators} + +Operators are listed below in order of increasing precedence. Operators +with equal precedence are grouped within { } symbols. + +\begin{verbatim} + expr1 | expr2 + Return the evaluation of expr1 if it is neither an empty string + nor zero; otherwise, returns the evaluation of expr2. + + expr1 & expr2 + Return the evaluation of expr1 if neither expression evaluates to + an empty string or zero; otherwise, returns zero. + + expr1 {=, >, >=, <, <=, !=} expr2 + Return the results of integer comparison if both arguments are + integers; otherwise, returns the results of string comparison + using the locale-specific collation sequence. The result of each + comparison is 1 if the specified relation is true, or 0 if the + relation is false. + + expr1 {+, -} expr2 + Return the results of addition or subtraction of integer-valued + arguments. + + expr1 {*, /, %} expr2 + Return the results of multiplication, integer division, or + remainder of integer-valued arguments. + + - expr1 + Return the result of subtracting expr1 from 0. + This, the unary minus operator, is right associative, and + has the same precedence as the ! operator. + + ! expr1 + Return the result of a logical complement of expr1. + In other words, if expr1 is null, 0, an empty string, + or the string "0", return a 1. Otherwise, return a 0. + It has the same precedence as the unary minus operator, and + is also right associative. + + expr1 : expr2 + The `:' operator matches expr1 against expr2, which must be a + regular expression. The regular expression is anchored to the + beginning of the string with an implicit `^'. + + If the match succeeds and the pattern contains at least one regu- + lar expression subexpression `\(...\)', the string correspond- + ing to `\1' is returned; otherwise the matching operator + returns the number of characters matched. If the match fails and + the pattern contains a regular expression subexpression the null + string is returned; otherwise 0. + + Normally, the double quotes wrapping a string are left as part + of the string. This is disastrous to the : operator. Therefore, + before the regex match is made, beginning and ending double quote + characters are stripped from both the pattern and the string. + + expr1 =~ expr2 + Exactly the same as the ':' operator, except that the match is + not anchored to the beginning of the string. Pardon any similarity + to seemingly similar operators in other programming languages! + The ":" and "=~" operators share the same precedence. + + expr1 ? expr2 :: expr3 + Traditional Conditional operator. If expr1 is a number + that evaluates to 0 (false), expr3 is result of the this + expression evaluation. Otherwise, expr2 is the result. + If expr1 is a string, and evaluates to an empty string, + or the two characters (""), then expr3 is the + result. Otherwise, expr2 is the result. In Asterisk, all + 3 exprs will be "evaluated"; if expr1 is "true", expr2 + will be the result of the "evaluation" of this + expression. expr3 will be the result otherwise. This + operator has the lowest precedence. +\end{verbatim} + +Parentheses are used for grouping in the usual manner. + +Operator precedence is applied as one would expect in any of the C +or C derived languages. + +\subsection{Examples} + +\begin{verbatim} + "One Thousand Five Hundred" =~ "(T[^ ]+)" + returns: Thousand + + "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 8 + + "One Thousand Five Hundred" : "T[^ ]+" + returns: 0 + + "8015551212" : "(...)" + returns: 801 + + "3075551212":"...(...)" + returns: 555 + + ! "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 0 (because it applies to the string, which is non-null, + which it turns to "0", and then looks for the pattern + in the "0", and doesn't find it) + + !( "One Thousand Five Hundred" : "T[^ ]+" ) + returns: 1 (because the string doesn't start with a word starting + with T, so the match evals to 0, and the ! operator + inverts it to 1 ). + + 2 + 8 / 2 + returns 6. (because of operator precedence; the division is done first, then the addition). + + 2+8/2 + returns 6. Spaces aren't necessary. + +(2+8)/2 + returns 5, of course. +\begin{verbatim} + +Of course, all of the above examples use constants, but would work the +same if any of the numeric or string constants were replaced with a +variable reference \${CALLERIDNUM}, for instance. + + +\subsection{Numbers Vs. Strings} + +Tokens consisting only of numbers are converted to 64-bit numbers for +most of the operators. This means that overflows can occur when the +numbers get above 18 digits. Warnings will appear in the logs in this +case. + +\subsection{Conditionals} + +There is one conditional application - the conditional goto : + +\begin{verbatim} + exten => 1,2,gotoif(condition?label1:label2) +\end{verbatim} + +If condition is true go to label1, else go to label2. Labels are interpreted +exactly as in the normal goto command. + +"condition" is just a string. If the string is empty or "0", the condition +is considered to be false, if it's anything else, the condition is true. +This is designed to be used together with the expression syntax described +above, eg : + +\begin{verbatim} + exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1) +\end{verbatim} + +Example of use : + +\begin{verbatim} +exten => s,2,Set(vara=1) +exten => s,3,Set(varb=$[${vara} + 2]) +exten => s,4,Set(varc=$[${varb} * 2]) +exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6) +\end{verbatim} + +\subsection{Parse Errors} + +Syntax errors are now output with 3 lines. + +If the extensions.conf file contains a line like: + +\begin{verbatim} +exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) +\end{verbatim} + +You may see an error in /var/log/asterisk/messages like this: +\begin{verbatim} +Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input: +"3072312154" = "3071234567" & & "Steves Extension" : "Privacy Manager" + ^ +\end{verbatim} + +The log line tells you that a syntax error was encountered. It now +also tells you (in grand standard bison format) that it hit an "AND" +(\&) token unexpectedly, and that was hoping for for a MINUS (-), LP +(left parenthesis), or a plain token (a string or number). + +The next line shows the evaluated expression, and the line after +that, the position of the parser in the expression when it became confused, +marked with the "\^" character. + +\subsection{NULL Strings} +Testing to see if a string is null can be done in one of two different ways: +\begin{verbatim} + exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) + + exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) +\end{verbatim} + +The second example above is the way suggested by the WIKI. It will +work as long as there are no spaces in the evaluated value. + +The first way should work in all cases, and indeed, might now +be the safest way to handle this situation. + +\subsection{Warning} + +If you need to do complicated things with strings, asterisk expressions +is most likely NOT the best way to go about it. AGI scripts are an +excellent option to this need, and make available the full power of +whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java, +Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula, +Pascal, APL, assembler, etc. + +\subsection{Incompatabilities} + +The asterisk expression parser has undergone some evolution. It is hoped +that the changes will be viewed as positive. + +The "original" expression parser had a simple, hand-written scanner, +and a simple bison grammar. This was upgraded to a more involved bison +grammar, and a hand-written scanner upgraded to allow extra spaces, +and to generate better error diagnostics. This upgrade required bison +1.85, and part of the user community felt the pain of having to +upgrade their bison version. + +The next upgrade included new bison and flex input files, and the makefile +was upgraded to detect current version of both flex and bison, conditionally +compiling and linking the new files if the versions of flex and bison would +allow it. + +If you have not touched your extensions.conf files in a year or so, the +above upgrades may cause you some heartburn in certain circumstances, as +several changes have been made, and these will affect asterisk's behavior on +legacy extension.conf constructs. The changes have been engineered +to minimize these conflicts, but there are bound to be problems. + +The following list gives some (and most likely, not all) of areas +of possible concern with "legacy" extension.conf files: + +\begin{enumerate} +\item Tokens separated by space(s). + Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate + to the value '2', but '1+1' would evaluate to the string '1+1'. If this + behavior was depended on, then the expression evaluation will break. '1+1' + will now evaluate to '2', and something is not going to work right. + To keep such strings from being evaluated, simply wrap them in double + quotes: ' "1+1" ' + +\item The colon operator. In versions previous to double quoting, the + colon operator takes the right hand string, and using it as a + regex pattern, looks for it in the left hand string. It is given + an implicit \^ operator at the beginning, meaning the pattern + will match only at the beginning of the left hand string. + If the pattern or the matching string had double quotes around + them, these could get in the way of the pattern match. Now, + the wrapping double quotes are stripped from both the pattern + and the left hand string before applying the pattern. This + was done because it recognized that the new way of + scanning the expression doesn't use spaces to separate tokens, + and the average regex expression is full of operators that + the scanner will recognize as expression operators. Thus, unless + the pattern is wrapped in double quotes, there will be trouble. + For instance, \${VAR1} : (Who|What*)+ + may have have worked before, but unless you wrap the pattern + in double quotes now, look out for trouble! This is better: + "\${VAR1}" : "(Who|What*)+" + and should work as previous. + +\item Variables and Double Quotes + Before these changes, if a variable's value contained one or more double + quotes, it was no reason for concern. It is now! + +\item LE, GE, NE operators removed. The code supported these operators, + but they were not documented. The symbolic operators, <=, >=, and != + should be used instead. + +\item Added the unary '-' operator. So you can 3+ -4 and get -1. + +\item Added the unary '!' operator, which is a logical complement. + Basically, if the string or number is null, empty, or '0', + a '1' is returned. Otherwise a '0' is returned. + +\item Added the '=~' operator, just in case someone is just looking for + match anywhere in the string. The only diff with the ':' is that + match doesn't have to be anchored to the beginning of the string. + +\item Added the conditional operator 'expr1 ? true\_expr :: false\_expr' + First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr' + is returned as the result. See above for details. + +\item Unary operators '-' and '!' were made right associative. +\end{enumerate} + +\subsection{Debugging Hints} + +There are two utilities you can build to help debug the \$[ ] in +your extensions.conf file. + +The first, and most simplistic, is to issue the command: + +make testexpr2 + +in the top level asterisk source directory. This will build a small +executable, that is able to take the first command line argument, and +run it thru the expression parser. No variable substitutions will be +performed. It might be safest to wrap the expression in single +quotes... + +testexpr2 '2*2+2/2' + +is an example. + +And, in the utils directory, you can say: + +make check\_expr + +and a small program will be built, that will check the file mentioned +in the first command line argument, for any expressions that might be +have problems when you move to flex-2.5.31. It was originally +designed to help spot possible incompatibilities when moving from the +pre-2.5.31 world to the upgraded version of the lexer. + +But one more capability has been added to check\_expr, that might make +it more generally useful. It now does a simple minded evaluation of +all variables, and then passes the \$[] exprs to the parser. If there +are any parse errors, they will be reported in the log file. You can +use check\_expr to do a quick sanity check of the expressions in your +extensions.conf file, to see if they pass a crude syntax check. + +The "simple-minded" variable substitution replaces \${varname} variable +references with '555'. You can override the 555 for variable values, +by entering in var=val arguments after the filename on the command +line. So... + + check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121 + +will substitute any \${CALLERIDNUM} variable references with +3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and +any \${EXTEN} references with '121'. If there is any fancy stuff +going on in the reference, like \${EXTEN:2}, then the override will +not work. Everything in the \${...} has to match. So, to substitute +\${EXTEN:2} references, you'd best say: + + check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121 + +on stdout, you will see something like: + + OK -- \$[ "\${DIALSTATUS}" = "TORTURE" | "\${DIALSTATUS}" = "DONTCALL" ] at line 416 + +In the expr2\_log file that is generated, you will see: + + line 416, evaluation of \$[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 + +check\_expr is a very simplistic algorithm, and it is far from being +guaranteed to work in all cases, but it is hoped that it will be +useful. + +\section{Asterisk standard channel variables} + +There are a number of variables that are defined or read +by Asterisk. Here is a list of them. More information is +available in each application's help text. All these variables +are in UPPER CASE only. + +Variables marked with a * are builtin functions and can't be set, +only read in the dialplan. Writes to such variables are silently +ignored. + +\begin{verbatim} +${ACCOUNTCODE} * Account code (if specified) (Deprecated; use ${CDR(accountcode)}) +${BLINDTRANSFER} The name of the channel on the other side of a blind transfer +${BRIDGEPEER} Bridged peer +${CALLERANI} * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)}) +${CALLERID} * Caller ID (Deprecated; use ${CALLERID(all)}) +${CALLERIDNAME} * Caller ID Name only (Deprecated; use ${CALLERID(name)}) +${CALLERIDNUM} * Caller ID Number only (Deprecated; use ${CALLERID(num)}) +${CALLINGANI2} * Caller ANI2 (PRI channels) +${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels) +${CALLINGTNS} * Transit Network Selector (PRI channels) +${CALLINGTON} * Caller Type of Number (PRI channels) +${CHANNEL} * Current channel name +${CONTEXT} * Current context +${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)}) +${DB_RESULT} Result value of DB_EXISTS() dial plan function +${DNID} * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)}) +${EPOCH} * Current unix style epoch +${EXTEN} * Current extension +${ENV(VAR)} Environmental variable VAR +${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority + after a blind transfer (use ^ characters in place of + | to separate context/extension/priority when setting + this variable from the dialplan) +${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound) +${HINT} * Channel hints for this extension +${HINTNAME} * Suggested Caller*ID name for this extension +${INVALID_EXTEN} The invalid called extension (used in the "i" extension) +${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()}) +${LEN(VAR)} * String length of VAR (integer) +${PRIORITY} * Current priority in the dialplan +${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed +${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)}) +${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}) +${TRANSFER_CONTEXT} Context for transferred calls +${FORWARD_CONTEXT} Context for forwarded calls +${UNIQUEID} * Current call unique identifier +${SYSTEMNAME} * value of the systemname option of asterisk.conf +\end{verbatim} + +\subsection{Application return values} +------------------------- +In Asterisk 1.2, many applications return the result in a variable +instead of, as in Asterisk 1.0, changing the dial plan priority (+101). +For the various status values, see each application's help text. +\begin{verbatim} +${AGISTATUS} * agi() +${AQMSTATUS} * addqueuemember() +${AVAILSTATUS} * chanisavail() +${CHECKGROUPSTATUS} * checkgroup() +${CHECKMD5STATUS} * checkmd5() +${CPLAYBACKSTATUS} * controlplayback() +${DIALSTATUS} * dial() +${DBGETSTATUS} * dbget() +${ENUMSTATUS} * enumlookup() +${HASVMSTATUS} * hasnewvoicemail() +${LOOKUPBLSTATUS} * lookupblacklist() +${OSPAUTHSTATUS} * ospauth() +${OSPLOOKUPSTATUS} * osplookup() +${OSPNEXTSTATUS} * ospnext() +${OSPFINISHSTATUS} * ospfinish() +${PARKEDAT} * parkandannounce() +${PLAYBACKSTATUS} * playback() +${PQMSTATUS} * pausequeuemember() +${PRIVACYMGRSTATUS} * privacymanager() +${QUEUESTATUS} * queue() +${RQMSTATUS} * removequeuemember() +${SENDIMAGESTATUS} * sendimage() +${SENDTEXTSTATUS} * sendtext() +${SENDURLSTATUS} * sendurl() +${SYSTEMSTATUS} * system() +${TRANSFERSTATUS} * transfer() +${TXTCIDNAMESTATUS} * txtcidname() +${UPQMSTATUS} * unpausequeuemember() +${VMSTATUS} * voicmail() +${VMBOXEXISTSSTATUS} * vmboxexists() +${WAITSTATUS} * waitforsilence() +\end{verbatim} + +\subsection{Various application variables} +\begin{verbatim} +${CURL} * Resulting page content for curl() +${ENUM} * Result of application EnumLookup +${EXITCONTEXT} Context to exit to in IVR menu (app background()) + or in the RetryDial() application +${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor()) +${MONITOR_EXEC} Application to execute after monitoring a call +${MONITOR_EXEC_ARGS} Arguments to application +${MONITOR_FILENAME} File for monitoring (recording) calls in queue +${QUEUE_PRIO} Queue priority +${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller +${QUEUESTATUS} Status of the call, one of: + (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL) +${RECORDED_FILE} * Recorded file in record() +${TALK_DETECTED} * Result from talkdetect() +${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record) +${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record) +${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record) +${TXTCIDNAME} * Result of application TXTCIDName +${VPB_GETDTMF} chan_vpb +\end{verbatim} + +\subsection{The MeetMe Conference Bridge} +\begin{verbatim} +${MEETME_RECORDINGFILE} Name of file for recording a conference with + the "r" option +${MEETME_RECORDINGFORMAT} Format of file to be recorded +${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting +${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only) +${MEETMESECS} * Number of seconds a user participated in a MeetMe conference +\end{verbatim} + +\subsection{The VoiceMail() application} +\begin{verbatim} +${VM_CATEGORY} Sets voicemail category +${VM_NAME} * Full name in voicemail +${VM_DUR} * Voicemail duration +${VM_MSGNUM} * Number of voicemail message in mailbox +${VM_CALLERID} * Voicemail Caller ID (Person leaving vm) +${VM_CIDNAME} * Voicemail Caller ID Name +${VM_CIDNUM} * Voicemail Caller ID Number +${VM_DATE} * Voicemail Date +${VM_MESSAGEFILE} * Path to message left by caller +\end{verbatim} + +\subsection{The VMAuthenticate() application} +\begin{verbatim} +${AUTH_MAILBOX} * Authenticated mailbox +${AUTH_CONTEXT} * Authenticated mailbox context +\end{verbatim} + +\subsection{DUNDiLookup()} +\begin{verbatim} +${DUNDTECH} * The Technology of the result from a call to DUNDiLookup() +${DUNDDEST} * The Destination of the result from a call to DUNDiLookup() +\end{verbatim} + +\subsection{chan\_zap} +\begin{verbatim} +${ANI2} * The ANI2 Code provided by the network on the incoming call. + (ie, Code 29 identifies call as a Prison/Inmate Call) +${CALLTYPE} * Type of call (Speech, Digital, etc) +${CALLEDTON} * Type of number for incoming PRI extension + i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, + 4=subscriber, 6=abbreviated, 7=reserved +${CALLINGSUBADDR} * Called PRI Subaddress +${FAXEXTEN} * The extension called before being redirected to "fax" +${PRIREDIRECTREASON} * Reason for redirect, if a call was directed +${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type' + of message 'b' or 'u' +\end{verbatim} + +\subsection{chan\_sip} +\begin{verbatim} +${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching) +${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate) +${SIPUSERAGENT} * SIP user agent (deprecated) +${SIPURI} * SIP uri +${SIP_CODEC} Set the SIP codec for a call +${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call +${RTPAUDIOQOS} RTCP QoS report for the audio of this call +${RTPVIDEOQOS} RTCP QoS report for the video of this call +\end{verbatim} + +\subsection{chan\_agent} +\begin{verbatim} +${AGENTMAXLOGINTRIES} Set the maximum number of failed logins +${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data +${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out +${AGENTACKCALL} Whether the agent should acknowledge the incoming call +${AGENTAUTOLOGOFF} Auto logging off for an agent +${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls +${AGENTNUMBER} * Agent number (username) set at login +${AGENTSTATUS} * Status of login ( fail | on | off ) +${AGENTEXTEN} * Extension for logged in agent +\end{verbatim} + + +\subsection{The Dial() application} +\begin{verbatim} +${DIALEDPEERNAME} * Dialed peer name +${DIALEDPEERNUMBER} * Dialed peer number +${DIALEDTIME} * Time for the call (seconds) +${ANSWEREDTIME} * Time from dial to answer (seconds) +${DIALSTATUS} * Status of the call, one of: + (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER + | ANSWER | CANCEL | DONTCALL | TORTURE) +${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of + features.conf) to activate during the call, with feature + names separated by '#' characters +${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits +${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits +${LIMIT_WARNING_FILE} Soundfile for call limits +${LIMIT_TIMEOUT_FILE} Soundfile for call limits +${LIMIT_CONNECT_FILE} Soundfile for call limits +${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup) +* See "show application dial" for more information +\end{verbatim} + +\subsection{The chanisavail() application} +\begin{verbatim} +${AVAILCHAN} * the name of the available channel if one was found +${AVAILORIGCHAN} * the canonical channel name that was used to create the channel +${AVAILSTATUS} * Status of requested channel +\end{verbatim} + +\subsection{Dialplan Macros} +\begin{verbatim} +${MACRO_EXTEN} * The calling extensions +${MACRO_CONTEXT} * The calling context +${MACRO_PRIORITY} * The calling priority +${MACRO_OFFSET} Offset to add to priority at return from macro +\end{verbatim} + +\subsection{The ChanSpy() application} +\begin{verbatim} +${SPYGROUP} * A ':' (colon) separated list of group names. + (To be set on spied on channel and matched against the g(grp) option) +\end{verbatim} + +\subsection{OSP} +\begin{verbatim} +${OSPINHANDLE} OSP handle of in_bound call +${OSPINTIMELIMIT} Duration limit for in_bound call +${OSPOUTHANDLE} OSP handle of out_bound call +${OSPTECH} OSP technology +${OSPDEST} OSP destination +${OSPCALLING} OSP calling number +${OSPOUTTOKEN} OSP token to use for out_bound call +${OSPOUTTIMELIMIT} Duration limit for out_bound call +${OSPRESULTS} Number of remained destinations +\end{verbatim} diff --git a/doc/tex/cliprompt.tex b/doc/tex/cliprompt.tex new file mode 100644 index 000000000..859943120 --- /dev/null +++ b/doc/tex/cliprompt.tex @@ -0,0 +1,30 @@ +\subsubsection{Changing the CLI Prompt} + +The CLI prompt is set with the ASTERISK\_PROMPT UNIX environment variable that +you set from the Unix shell before starting Asterisk + +You may include the following variables, that will be replaced by +the current value by Asterisk: + +\begin{verbatim} +%d Date (year-month-date) +%s Asterisk system name (from asterisk.conf) +%h Full hostname +%H Short hostname +%t Time +%% Percent sign +%# '#' if Asterisk is run in console mode, '>' if running as remote console +%Cn[;n] Change terminal foreground (and optional background) color to specified +\end{verbatim} + +A full list of colors may be found in include/asterisk/term.h + +On Linux systems, you may also use: + +\begin{verbatim} +%l1 Load average over past minute +%l2 Load average over past 5 minutes +%l3 Load average over past 15 minutes +%l4 Process fraction (processes running / total processes) +%l5 The most recently allocated pid +\end{verbatim} diff --git a/doc/tex/configuration.tex b/doc/tex/configuration.tex new file mode 100644 index 000000000..a501928bb --- /dev/null +++ b/doc/tex/configuration.tex @@ -0,0 +1,198 @@ +\subsubsection{Introduction} + +The Asterisk configuration parser in the 1.2 version +and beyond series has been improved in a number of ways. In +addition to the realtime architecture, we now have the ability to create +templates in configuration files, and use these as templates when we +configure phones, voicemail accounts and queues. + +These changes are general to the configuration parser, and works in +all configuration files. + +\subsubsection{General syntax} +Asterisk configuration files are defined as follows: + +\begin{verbatim} + [section] + label = value + label2 = value +\end{verbatim} + +In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax +is a bit different. In these files the syntax is as follows: + +\begin{verbatim} + [section] + label1 = value1 + label2 = value2 + object => name + + label3 = value3 + label2 = value4 + object2 => name2 +\end{verbatim} + +In this syntax, we create objects with the settings defined above the object +creation. Note that settings are inherited from the top, so in the example +above object2 has inherited the setting for "label1" from the first object. + +For template configurations, the syntax for defining a section is changed +to: +\begin{verbatim} + [section](options) + label = value +\end{verbatim} + +The options field is used to define templates, refer to templates and hide +templates. Any object can be used as a template. + +No whitespace is allowed between the closing "]" and the parenthesis "(". + +\subsubsection{Comments} + +All lines that starts with semi-colon ";" is treated as comments +and is not parsed. + +The ";--" is a marker for a multi-line comment. Everything after +that marker will be treated as a comment until the end-marker "--;" +is found. Parsing begins directly after the end-marker. + +\begin{verbatim} + ;This is a comment + label = value + ;-- This is + a comment --; + + ;-- Comment --; exten=> 1000,1,dial(SIP/lisa) +\end{verbatim} + +\subsubsection{Including other files} +In all of the configuration files, you may include the content of another +file with the \#include statement. The content of the other file will be +included at the row that the \#include statement occurred. + +\begin{verbatim} + #include myusers.conf +\end{verbatim} + +You may also include the output of a program with the \#exec directive, +if you enable it in asterisk.conf + +In asterisk.conf, add the execincludes = yes statement in the options +section: +\begin{verbatim} + [options] + execincludes=yes +\end{verbatim} + +The exec directive is used like this: + +\begin{verbatim} + #exec /usr/local/bin/myasteriskconfigurator.sh +\end{verbatim} + +\subsubsection{Adding to an existing section} +\begin{verbatim} + [section] + label = value + + [section](+) + label2 = value2 +\end{verbatim} + +In this case, the plus sign indicates that the second section (with the +same name) is an addition to the first section. The second section can +be in another file (by using the \#include statement). If the section +name referred to before the plus is missing, the configuration will fail +to load. + +\subsubsection{Defining a template-only section} +\begin{verbatim} + [section](!) + label = value +\end{verbatim} + +The exclamation mark indicates to the config parser that this is a only +a template and should not itself be used by the Asterisk module for +configuration. The section can be inherited by other sections (see +section "Using templates" below) but is not used by itself. + +\subsubsection{Using templates (or other configuration sections)} +\begin{verbatim} + [section](name[,name]) + label = value +\end{verbatim} + +The name within the parenthesis refers to other sections, either +templates or standard sections. The referred sections are included +before the configuration engine parses the local settings within the +section as though their entire contents (and anything they were +previously based upon) were included in the new section. For example +consider the following: + +\begin{verbatim} +[foo] +permit=192.168.0.2 +host=asdf +deny=192.168.0.1 + +[bar] +permit=192.168.1.2 +host=jkl +deny=192.168.1.1 + +[baz](foo,bar) +permit=192.168.3.1 +host=bnm +\end{verbatim} + +The [baz] section will be processed as though it had been written in the +following way: + +\begin{verbatim} +[baz] +permit=192.168.0.2 +host=asdf +deny=192.168.0.1 +permit=192.168.1.2 +host=jkl +deny=192.168.1.1 +permit=192.168.3.1 +host=bnm +\end{verbatim} + +\subsubsection{Additional Examples} + +(in top-level sip.conf) + +\begin{verbatim} +[defaults](!) +type=friend +nat=yes +qualify=on +dtmfmode=rfc2833 +disallow=all +allow=alaw + +#include accounts/*/sip.conf +\end{verbatim} + +(in accounts/customer1/sip.conf) + +\begin{verbatim} +[def-customer1](!,defaults) +secret=this_is_not_secret +context=from-customer1 +callerid=Customer 1 <300> +accountcode=0001 + +[phone1](def-customer1) +mailbox=phone1@customer1 + +[phone2](def-customer1) +mailbox=phone2@customer1 +\end{verbatim} + +This example defines two phones - phone1 and phone2 with settings +inherited from "def-customer1". The "def-customer1" is a template that +inherits from "defaults", which also is a template. diff --git a/doc/tex/dundi.tex b/doc/tex/dundi.tex new file mode 100644 index 000000000..c932da48c --- /dev/null +++ b/doc/tex/dundi.tex @@ -0,0 +1,40 @@ +http://www.dundi.com +Mark Spencer, Digium, Inc. + +DUNDi is essentially a trusted, peer-to-peer system for being able to +call any phone number from the Internet. DUNDi works by creating a +network of nodes called the "DUNDi E.164 Trust Group" which are bound by +a common peering agreement known as the General Peering Agreement or +GPA. The GPA legally binds the members of the Trust Group to provide +good-faith accurate information to the other nodes on the network, and +provides standards by which the community can insure the integrity of +the information on the nodes themselves. Unlike ENUM or similar +systems, DUNDi is explicitly designed to preclude any necessity for a +single centralized system which could be a source of fees, regulation, +etc. + +Much less dramatically, DUNDi can also be used within a private +enterprise to share a dialplan efficiently between multiple nodes, +without incurring a risk of a single point of failure. In this way, +administrators can locally add extensions which become immediately +available to the other nodes in the system. + +For more information visit http://www.dundi.com + +\section{DUNDIQUERY and DUNDIRESULT} + +The DUNDIQUERY and DUNDIRESULT dialplan functions will let you initiate +a DUNDi query from the dialplan, see how many results there are, and access +each one. Here is some example usage: + +\begin{verbatim} +exten => 1,1,Set(ID=${DUNDIQUERY(1|dundi_test|b)}) +exten => 1,n,Set(NUM=${DUNDIRESULT(${ID}|getnum)}) +exten => 1,n,NoOp(There are ${NUM} results) +exten => 1,n,Set(X=1) +exten => 1,n,While($[${X} <= ${NUM}]) +exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID}|${X})}) +exten => 1,n,Set(X=$[${X} + 1]) +exten => 1,n,EndWhile +\end{verbatim} + diff --git a/doc/tex/enum.tex b/doc/tex/enum.tex new file mode 100644 index 000000000..699042d18 --- /dev/null +++ b/doc/tex/enum.tex @@ -0,0 +1,353 @@ +\section{The ENUMLOOKUP dialplan function} + +The ENUMLOOKUP function is more complex than it first may appear, and +this guide is to give a general overview and set of examples that may +be well-suited for the advanced user to evaluate in their +consideration of ENUM or ENUM-like lookup strategies. This document +assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as +well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404). +For an overview of NAPTR records, and the use of NAPTRs in the ENUM +global phone-number-to-DNS mapping scheme, please see +http://www.voip-info.org/tiki-index.php?page=ENUM for more detail. + +Using ENUM within Asterisk can be simple or complex, depending on how +many failover methods and redundancy procedures you wish to utilize. +Implementation of ENUM paths is supposedly defined by the person +creating the NAPTR records, but the local administrator may choose to +ignore certain NAPTR response methods (URI types) or prefer some over +others, which is in contradiction to the RFC. The ENUMLOOKUP method +simply provides administrators a method for determining NAPTR results +in either the globally unique ENUM (e164.arpa) DNS tree, or in other +ENUM-like DNS trees which are not globally unique. The methods to +actually create channels ("dial") results given by the ENUMLOOKUP +function is then up to the administrator to implement in a way that +best suits their environment. + +\begin{verbatim} +Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]]) +\end{verbatim} + + Performs an ENUM tree lookup on the specified number, method type, and + ordinal record offset, and returns one of four different values: + +\begin{enumerate} + \item post-parsed NAPTR of one method (URI) type + \item count of elements of one method (URI) type + \item count of all method types + \item full URI of method at a particular point in the list of all possible methods +\end{enumerate} + +\subsection{Arguments} + +\begin{itemize} + \item number + \begin{itemize} + \item telephone number or search string. Only numeric values + within this string are parsed; all other digits are ignored for + search, but are re-written during NAPTR regexp expansion. + \end{itemize} + + \item service\_type + \begin{itemize} + \item tel, sip, h323, iax2, mailto, ...[any other string], + ALL. Default type is "sip". + Special name of "ALL" will create a list of method types across + all NAPTR records for the search number, and then put the results + in an ordinal list starting with 1. The position <number> + specified will then be returned, starting with 1 as the first + record (lowest value) in the list. The service types are not + hardcoded in Asterisk except for the default (sip) if no other + service type specified; any method type string (IANA-approved or + not) may be used except for the string "ALL". + \end{itemize} + + \item options + \begin{itemize} + \item c + \begin{itemize} + \item count. Returns the number of records of this type are returned + (regardless of order or priority.) If "ALL" is the specified + service\_type, then a count of all methods will be returned for the + DNS record. + \end{itemize} + \end{itemize} + + \item record\# + \begin{itemize} + \item which record to present if multiple answers are returned + <integer> = The record in priority/order sequence based on the + total count of records passed back by the query. If a service\_type + is specified, all entries of that type will be sorted into an + ordinal list starting with 1 (by order first, then priority). + The default of <options> is "1" + \end{itemize} + + \item zone\_suffix + \begin{itemize} + \item allows customization of the ENUM zone. Default is e164.arpa. + \end{itemize} +\end{itemize} + +\subsection{Examples} + +Let's use this ENUM list as an example (note that these examples exist +in the DNS, and will hopefully remain in place as example +destinations, but they may change or become invalid over time. The +end result URIs are not guaranteed to actually work, since some of +these hostnames or SIP proxies are imaginary. Of course, the tel: +replies go to directory assistance for New York City and San +Francisco...) Also note that the complex SIP NAPTR at weight 30 will +strip off the leading "+" from the dialed string if it exists. This +is probably a better NAPTR than hard-coding the number into the NAPTR, +and it is included as a more complex regexp example, though other +simpler NAPTRs will work just as well. + +\begin{verbatim} +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 10 100 "u" + "E2U+tel" "!^\\+13015611020$!tel:+12125551212!" . +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 21 100 "u" + "E2U+tel" "!^\\+13015611020$!tel:+14155551212!" . +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 25 100 "u" + "E2U+sip" "!^\\+13015611020$!sip:2203@sip.fox-den.com!" . +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 26 100 "u" + "E2U+sip" "!^\\+13015611020$!sip:1234@sip-2.fox-den.com!" . +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 30 100 "u" + "E2U+sip" "!^\\+*([^\\*]*)!sip:\\1@sip-3.fox-den.com!" . +0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 55 100 "u" + "E2U+mailto" "!^\\+13015611020$!mailto:jtodd@fox-den.com!" . +\end{verbatim} + +Example 1: Simplest case, using first SIP return (use all defaults +except for domain name) +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,,loligo.com)}) + returns: ${foo}="2203@sip.fox-den.com" +\end{verbatim} + +Example 2: What is the first "tel" pointer type for this number? +(after sorting by order/preference; default of "1" is assumed in +options field) +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,,loligo.com)}) + returns: ${foo}="+12125551212" +\end{verbatim} + +Example 3: How many "sip" pointer type entries are there for this number? +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,,loligo.com)}) + returns: ${foo}=3 +\end{verbatim} + +Example 4: For all the "tel" pointer type entries, what is the second +one in the list? (after sorting by preference) +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,2,loligo.com)}) + returns: ${foo}="+14155551212" +\end{verbatim} + +Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number? +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,,loligo.com)}) + returns: ${foo}=6 +\end{verbatim} + +Example 6: Give back the second full URI in the sorted list of all NAPTR URIs: +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,,2,loligo.com)}) + returns: ${foo}="tel:+14155551212" [note the "tel:" prefix in the string] +\end{verbatim} + +Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults) +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)}) + returns: ${foo}="enum-test@sip.nemox.net" [note: this result is + subject to change as it is "live" DNS and not under my control] +\end{verbatim} + +Example 8: Look up the ISN mapping in freenum.org alpha test zone +\begin{verbatim} +exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,,freenum.org)}) + returns: ${foo}="1234@204.91.156.10" [note: this result is subject + to change as it is "live" DNS] +\end{verbatim} + +Example 9: Give back the first SIP pointer for a number in the +\begin{verbatim} +enum.yoydynelabs.com zone (invalid lookup) +exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) + returns: ${foo}="" +\end{verbatim} + +\subsection{Usage notes and subtle features} +\begin{itemize} + \item The use of "+" in lookups is confusing, and warrants further + explanation. All E.164 numbers ("global phone numbers") by + definition need a leading "+" during ENUM lookup. If you neglect to + add a leading "+", you may discover that numbers that seem to exist + in the DNS aren't getting matched by the system or are returned with + a null string result. This is due to the NAPTR reply requiring a + "+" in the regular expression matching sequence. Older versions of + Asterisk add a "+" from within the code, which may confuse + administrators converting to the new function. Please ensure that + all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so + ensure your lookup includes the leading plus sign. Other DNS trees + may or may not require a leading "+" - check before using those + trees, as it is possible the parsed NAPTRs will not provide correct + results unless you have the correct dialed string. If you get + console messages like "WARNING[24907]: enum.c:222 parse\_naptr: NAPTR + Regex match failed." then it is very possible that the returned + NAPTR expects a leading "+" in the search string (or the returned + NAPTR is mis-formed.) + + \item If a query is performed of type "c" ("count") and let's say you + get back 5 records and then some seconds later a query is made + against record 5 in the list, it may not be the case that the DNS + resolver has the same answers as it did a second or two ago - maybe + there are only 4 records in the list in the newest query. The + resolver should be the canonical storage location for DNS records, + since that is the intent of ENUM. However, some obscure future + cases may have wildly changing NAPTR records within several seconds. + This is a corner case, and probably only worth noting as a very rare + circumstance. (note: I do not object to Asterisk's dnsmgr method of + locally caching DNS replies, but this method needs to honor the TTL + given by the remote zone master. Currently, the ENUMLOOKUP function + does not use the dnsmgr method of caching local DNS replies.) + + \item If you want strict NAPTR value ordering, then it will be + necessary to use the "ALL" method to incrementally step through the + different returned NAPTR pointers. You will need to use string + manipulation to strip off the returned method types, since the + results will look like "sip:12125551212" in the returned value. + This is a non-trivial task, though it is required in order to have + strict RFC compliance and to comply with the desires of the remote + party who is presenting NAPTRs in a particular order for a reason. + + \item Default behavior for the function (even in event of an error) is + to move to the next priority, and the result is a null value. Most + ENUM lookups are going to be failures, and it is the responsibility + of the dialplan administrator to manage error conditions within + their dialplan. This is a change from the old app\_enumlookup method + and it's arbitrary priority jumping based on result type or failure. + + \item Anything other than digits will be ignored in lookup strings. + Example: a search string of "+4372030blah01721" will turn into + 1.2.7.1.0.0.3.0.2.7.3.4.e164.arpa. for the lookup. The NAPTR + parsing may cause unexpected results if there are strings inside + your NAPTR lookups. + + \item If there exist multiple records with the same weight and order as + a result of your query, the function will RANDOMLY select a single + NAPTR from those equal results. + + \item Currently, the function ignores the settings in enum.conf as the + search zone name is now specified within the function, and the H323 + driver can be chosen by the user via the dialplan. There were no + other values in this file, and so it becomes deprecated. + + \item The function will digest and return NAPTRs which use older + (deprecated) style, reversed method strings such as "sip+E2U" + instead of the more modern "E2U+sip" + + \item There is no provision for multi-part methods at this time. If + there are multiple NAPTRs with (as an example) a method of + "E2U+voice:sip" and then another NAPTR in the same DNS record with a + method of ""E2U+sip", the system will treat these both as method + "sip" and they will be separate records from the perspective of the + function. Of course, if both records point to the same URI and have + equal priority/weight (as is often the case) then this will cause no + serious difficulty, but it bears mentioning. + + \item ISN (ITAD Subscriber Number) usage: If the search number is of + the form ABC*DEF (where ABC and DEF are at least one numeric digit) + then perform an ISN-style lookup where the lookup is manipulated to + C.B.A.DEF.domain.tld (all other settings and options apply.) See + http://www.freenum.org/ for more details on ISN lookups. In the + unlikely event you wish to avoid ISN re-writes, put an "n" as the + first digit of the search string - the "n" will be ignored for the search. +\end{itemize} + +\subsection{Some more Examples} + +All examples below except where noted use "e164.arpa" as the +referenced domain, which is the default domain name for ENUMLOOKUP. +All numbers are assumed to not have a leading "+" as dialed by the +inbound channel, so that character is added where necessary during +ENUMLOOKUP function calls. + +\begin{verbatim} +; example 1 +; +; Assumes North American international dialing (011) prefix. +; Look up the first SIP result and send the call there, otherwise +; send the call out a PRI. This is the most simple possible +; ENUM example, but only uses the first SIP reply in the list of +; NAPTR(s). +; +exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})}) +exten => _011.,n,Dial(SIP/${enumresult}) +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 1 + +; example 2 +; +; Assumes North American international dialing (011) prefix. +; Check to see if there are multiple SIP NAPTRs returned by +; the lookup, and dial each in order. If none work (or none +; exist) then send the call out a PRI, group 1. +; +exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0) +exten => _011.,n,While($["${counter}"<"${sipcount}"]) +exten => _011.,n,Set(counter=$[${counter}+1]) +exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})}) +exten => _011.,n,EndWhile +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 2 + +; example 3 +; +; This example expects an ${EXTEN} that is an e.164 number (like +; 14102241145 or 437203001721) +; Search through e164.arpa and then also search through e164.org +; to see if there are any valid SIP or IAX termination capabilities. +; If none, send call out via Zap channel 1. +; +; Start first with e164.arpa zone... +; +exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0) +exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6) +exten => _X.,3,Set(counter=$[${counter}+1]) +exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})}) +exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6) +; +exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0) +exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +exten => _X.,8,Set(counter=$[${counter}+1]) +exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})}) +exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +; +exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org") +; +; ...then also try e164.org, and look for SIP and IAX NAPTRs... +; +exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0) +exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17) +exten => _X.,14,Set(counter=$[${counter}+1]) +exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)}) +exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17) +; +exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0) +exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +exten => _X.,19,Set(counter=$[${counter}+1]) +exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)}) +exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +; +; ...then send out PRI. +; +exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap") +exten => _X.,23,Dial(Zap/g1/${EXTEN}) +; +; end example 3 + +\end{verbatim} diff --git a/doc/tex/extensions.tex b/doc/tex/extensions.tex new file mode 100644 index 000000000..28a49f092 --- /dev/null +++ b/doc/tex/extensions.tex @@ -0,0 +1,74 @@ +\subsubsection{The Asterisk dialplan} + +The Asterisk dialplan is divided into contexts. A context is simply a group +of extensions. For each "line" that should be able to be called, an extension +must be added to a context. Then, you configure the calling "line" to have +access to this context. + +If you change the dialplan, you can use the Asterisk CLI command +"extensions reload" to load the new dialplan without disrupting +service in your PBX. + +Extensions are routed according to priority and may be based on any set +of characters (a-z), digits, \#, and *. Please note that when matching a +pattern, "N", "X", and "Z" are interpreted as classes of digits. + +For each extension, several actions may be listed and must be given a unique +priority. When each action completes, the call continues at the next priority +(except for some modules which use explicitly GOTO's). + +When each action completes, it generally moves to the next priority (except for +some modules which use explicitly GOTO's. + +Extensions frequently have data they pass to the executing application +(most frequently a string). You can see the available dialplan applications +by entering the "show applications" command in the CLI. + +In this version of Asterisk, dialplan functions are added. These can +be used as arguments to any application. For a list of the installed +functions in your Asterisk, use the "show functions" command. + +\subsubsection{Example dialplan} + +The example dial plan, in the configs/extensions.conf.sample file +is installed as extensions.conf if you run "make samples" after +installation of Asterisk. This file includes many more instructions +and examples than this file, so it's worthwhile to read it. + +\subsubsection{Special extensions} + +There are some extensions with important meanings: + +\begin{itemize} + \item s + \begin{itemize} + \item What to do when an extension context is entered (unless + overridden by the low level channel interface) + This is used in macros, and some special cases. + "s" is not a generic catch-all wildcard extension. + \end{itemize} + \item i + \begin{itemize} + \item What to do if an invalid extension is entered + \end{itemize} + \item h + \begin{itemize} + \item The hangup extension, executed at hangup + \end{itemize} + \item t + \begin{itemize} + \item What to do if nothing is entered in the requisite amount + of time. + \end{itemize} + \item T + \begin{itemize} + \item This is the extension that is executed when the 'absolute' + timeout is reached. See "show function TIMEOUT" for more + information on setting timeouts. + \end{itemize} +\end{itemize} + +And finally, the extension context "default" is used when either a) an +extension context is deleted while an extension is in use, or b) a specific +starting extension handler has not been defined (unless overridden by the +low level channel interface). diff --git a/doc/tex/freetds.tex b/doc/tex/freetds.tex new file mode 100644 index 000000000..8dcbec29a --- /dev/null +++ b/doc/tex/freetds.tex @@ -0,0 +1,16 @@ +The cdr\_tds module is NOT compatible with version 0.63 of FreeTDS. + +The cdr\_tds module is known to work with FreeTDS version 0.62.1; +it should also work with 0.62.2, 0.62.3 and 0.62.4, which are bug +fix releases. + +The cdr\_tds module uses the raw "libtds" API of FreeTDS. It appears +that from 0.63 onwards, this is not considered a published API +of FreeTDS and is subject to change without notice. + +Between 0.62.x and 0.63 of FreeTDS, many incompatible changes +have been made to the libtds API. + +For newer versions of FreeTDS, it is recommended that you use the +ODBC driver. + diff --git a/doc/tex/hardware.tex b/doc/tex/hardware.tex new file mode 100644 index 000000000..3d7cabd82 --- /dev/null +++ b/doc/tex/hardware.tex @@ -0,0 +1,100 @@ +\subsection{Introduction} + +A PBX is only really useful if you can get calls into it. Of course, you +can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk +to the real PSTN through various cards. + +Supported Hardware is divided into two general groups: Zaptel devices and +non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM +conferencing and all call features through chan\_zap, whereas non-zaptel +compatible hardware may have different features. + +\subsection{Zaptel compatible hardware} + +\begin{itemize} +\item Digium, Inc. (Primary Developer of Asterisk) + http://www.digium.com + \begin{itemize} + \item Analog Interfaces + \begin{itemize} + \item TDM400P - The TDM400P is a half-length PCI 2.2-compliant card that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC. + \item TDM800P - The TDM800P is a half-length PCI 2.2-compliant, 8 port card using Digium's VoiceBus technology that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC. + \item TDM2400P - The TDM2400P is a full-length PCI 2.2-compliant card for connecting analog telephones and analog POTS lines through a PC. It supports a combination of up to 6 FXS and/or FXO modules for a total of 24 lines. + \end{itemize} + \item Digital Interfaces + \begin{itemize} + \item TE412P - The TE412P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE410P - The TE410P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE407P - The TE407P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE405P - The TE405P improves performance and scalability through bus mastering architecture. It supports both E1, T1, J1 environments and is selectable on a per-card or per-port basis. + \item TE212P - The TE212P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE210P - The TE210P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE207P - The TE207P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. + \item TE205P - The TE205P improves performance and scalability through bus mastering architecture. It supports both E1 and T1/J1 environments and is selectable on a per-card or per-port basis. + \item TE120P - The TE120P is a single span, selectable T1, E1, or J1 card and utilizes Digium's VoiceBus™ technology. It supports both voice and data modes. + \item TE110P - The TE110P brings a high-performance, cost-effective, and flexible single span togglable T1, E1, J1 interface to the Digium line-up of telephony interface devices. + \end{itemize} + \end{itemize} +\end{itemize} + +\subsection{Non-zaptel compatible hardware} + +\begin{itemize} + \item QuickNet, Inc. + http://www.quicknet.net + \begin{itemize} + \item Internet PhoneJack - Single FXS interface. Supports Linux telephony + interface. DSP compression built-in. + + \item Internet LineJack - Single FXS or FXO interface. Supports Linux + telephony interface. + \end{itemize} +\end{itemize} + +\subsection{mISDN compatible hardware} + +mISDN homepage: http://www.isdn4linux.de/mISDN/ + +Any adapter with an mISDN driver should be compatible with +chan\_misdn. See the mISDN section for more information. + +\begin{itemize} + \item Digium, Inc. (Primary Developer of Asterisk) + http://www.digium.com + \begin{itemize} + \item B410P - 4 Port BRI card (TE/NT) + \end{itemize} +\end{itemize} + +\begin{itemize} + \item beroNet + http://www.beronet.com + \begin{itemize} + \item BN4S0 - 4 Port BRI card (TE/NT) + + \item BN8S0 - 8 Port BRI card (TE/NT) + + \item Billion Card - Single Port BRI card (TE (/NT with crossed cable) ) + \end{itemize} +\end{itemize} + +\subsection{Miscellaneous other interfaces} + +\begin{itemize} + \item Digium, Inc. (Primary Developer of Asterisk) + \begin{itemize} + \item TC400B - The TC400B is a half-length, low-profile PCI 2.2-compliant card for transforming complex VoIP codecs (G.729) into simple codecs. + \end{itemize} + + \item ALSA + http://www.alsa-project.org + \begin{itemize} + \item Any ALSA compatible full-duplex sound card + \end{itemize} + + \item OSS + http://www.opensound.com + \begin{itemize} + \item Any OSS compatible full-duplex sound card + \end{itemize} +\end{itemize} diff --git a/doc/tex/ices.tex b/doc/tex/ices.tex new file mode 100644 index 000000000..77267b506 --- /dev/null +++ b/doc/tex/ices.tex @@ -0,0 +1,7 @@ +The advent of icecast into Asterisk allows you to do neat things like have +a caller stream right into an ice-cast stream as well as using chan\_local +to place things like conferences, music on hold, etc. into the stream. + +You'll need to specify a config file for the ices encoder. An example is +included in contrib/asterisk-ices.xml. + diff --git a/doc/tex/imapstorage.tex b/doc/tex/imapstorage.tex new file mode 100644 index 000000000..fccdc43bb --- /dev/null +++ b/doc/tex/imapstorage.tex @@ -0,0 +1,173 @@ +By enabling IMAP Storage, Asterisk will use native IMAP as the storage +mechanism for voicemail messages instead of using the standard file structure. + +Tighter integration of Asterisk voicemail and IMAP email services allows +additional voicemail functionality, including: + +\begin{itemize} + \item Listening to a voicemail on the phone will set its state to "read" in + a user's mailbox automatically. + \item Deleting a voicemail on the phone will delete it from the user's + mailbox automatically. + \item Accessing a voicemail recording email message will turn off the message + waiting indicator (MWI) on the user's phone. + \item Deleting a voicemail recording email will also turn off the message + waiting indicator, and delete the message from the voicemail system. +\end{itemize} + +\subsection{Installation Notes} + +\subsubsection{University of Washington IMAP C-Client} + +If you do not have the University of Washington's IMAP c-client +installed on your system, you will need to download the c-client +source distribution (http://www.washington.edu/imap/) and compile it. +Asterisk supports both the 2004 and 2006 versions of c-client, however +mail\_expunge\_full is enabled in the 2006 version. + +Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit, +but building it also builds an IMAP server and various other utilities. +Because of this, the build instructions for the IMAP toolkit are somewhat +complicated and can lead to confusion about what is needed. + +If you are going to be connecting Asterisk to an existing IMAP server, +then you don't need to care about the server or utilities in the IMAP +toolkit at all. If you want to also install the UW IMAPD server, that +is outside the scope of this document. + +Building the c-client library is fairly straightforward; for example, on a +Debian system there are two possibilities: + +\begin{verbatim} +1) if you will not be using SSL to connect to the IMAP server: + $ make slx SSLTYPE=none + +2) if you will be using SSL to connect to the IMAP server: + $ make slx EXTRACFLAGS="-I/usr/include/openssl" +\end{verbatim} + +Once this completes you can proceed with the Asterisk build; there is no +need to run 'make install'. + +\subsubsection{Compiling Asterisk} + +To use the system c-client library, configure Asterisk with +./configure --with-imap=system. If you downloaded the c-client source +and compiled it according to the above instructions, configure +Asterisk with with ./configure --with-imap=/usr/src/imap or where ever +you built the UWashington IMAP Toolkit. When you run 'make +menuselect', choose 'Voicemail Build Options' and the IMAP\_STORAGE +option should be available for selection. + +After selecting the IMAP\_STORAGE option, use the 'x' key to exit +menuselect and save your changes, and the build/install Asterisk +normally. + +\subsection{Modify voicemail.conf} + +The following directives have been added to voicemail.conf: + +\begin{verbatim} +imapserver=<name or IP address of IMAP mail server> +imapport=<IMAP port, defaults to 143> +imapflags=<IMAP flags, "novalidate-cert" for example> +expungeonhangup=<yes or no> +authuser=<username> +authpassword=<password> +\end{verbatim} + +The "expungeonhangup" flag is used to determine if the voicemail system should +expunge all messages marked for deletion when the user hangs up the phone. + +Each mailbox definition should also have imapuser=<imap username>. +For example: + +\begin{verbatim} +4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar +\end{verbatim} + +The directives "authuser" and "authpassword" are not needed when using +Kerberos. They are defined to allow Asterisk to authenticate as a single +user that has access to all mailboxes as an alternative to Kerberos. + + +\subsection{IMAP Folders} + +Besides INBOX, users should create "Old", "Work", "Family" and "Friends" +IMAP folders at the same level of hierarchy as the INBOX. These will be +used as alternate folders for storing voicemail messages to mimic the +behavior of the current (file-based) voicemail system. + + +\subsection{Separate vs. Shared Email Accounts} + +As administrator you will have to decide if you want to send the voicemail +messages to a separate IMAP account or use each user's existing IMAP mailbox +for voicemail storage. The IMAP storage mechanism will work either way. + +By implementing a single IMAP mailbox, the user will see voicemail messages +appear in the same INBOX as other messages. The disadvantage of this method +is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will +expunge ALL messages marked for deletion when the user exits the voicemail +system, not just the VOICEMAIL messages marked for deletion. + +By implementing separate IMAP mailboxes for voicemail and email, voicemail +expunges will not remove regular email flagged for deletion. + + +\subsection{IMAP Server Implementations} + +There are various IMAP server implementations, each supports a potentially +different set of features. + + +\subsubsection{UW IMAP-2005 or earlier} + +UIDPLUS is currently NOT supported on these versions of UW-IMAP. Please note +that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked +for deletion when a user exits the voicemail system (hangs up the phone). + +\subsubsection{UW IMAP-2006 Development Branch} + +This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities. This +feature allow the system to expunge ONLY pertinent messages, instead of the +default behavior, which is to expunge ALL messages marked for deletion when +EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk +will check if the UID\_EXPUNGE feature is supported by the server, and use it +if possible. + +\subsubsection{Cyrus IMAP} + +Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. + + +\subsection{Quota Support} + +If the IMAP server supports quotas, Asterisk will check the quota when +accessing voicemail. Currently only a warning is given to the user that +their quota is exceeded. + + +\subsection{Application Notes} + +Since the primary storage mechanism is IMAP, all message information that +was previously stored in an associated text file, AND the recording itself, +is now stored in a single email message. This means that the .gsm recording +will ALWAYS be attached to the message (along with the user's preference of +recording format if different - ie. .WAV). The voicemail message information +is stored in the email message headers. These headers include: + +\begin{verbatim} +X-Asterisk-VM-Message-Num +X-Asterisk-VM-Server-Name +X-Asterisk-VM-Context +X-Asterisk-VM-Extension +X-Asterisk-VM-Priority +X-Asterisk-VM-Caller-channel +X-Asterisk-VM-Caller-ID-Num +X-Asterisk-VM-Caller-ID-Name +X-Asterisk-VM-Duration +X-Asterisk-VM-Category +X-Asterisk-VM-Orig-date +X-Asterisk-VM-Orig-time +\end{verbatim} diff --git a/doc/tex/jitterbuffer.tex b/doc/tex/jitterbuffer.tex new file mode 100644 index 000000000..5122f1286 --- /dev/null +++ b/doc/tex/jitterbuffer.tex @@ -0,0 +1,98 @@ +\subsubsection{The new jitterbuffer} + +You must add "jitterbuffer=yes" to either the [general] part of +iax.conf, or to a peer or a user. (just like the old jitterbuffer). +Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the +jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer +on both sides of a call; it works on the receive side only. + +\subsubsection{PLC} + +The new jitterbuffer detects packet loss. PLC is done to try to recreate these +lost packets in the codec decoding stage, as the encoded audio is translated to slinear. +PLC is also used to mask jitterbuffer growth. + +This facility is enabled by default in iLBC and speex, as it has no additional cost. +This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting +genericplc => true in the [plc] section of codecs.conf. + +\subsubsection{Trunktimestamps} + +To use this, both sides must be using Asterisk v1.2 or later. +Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps +for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer +for an IAX2 trunk, something that was not possible in the old architecture. + +The other side must also support this functionality, or else, well, bad things will happen. +If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because +timestamps aren't necessarily sent through the trunk correctly. + +\subsubsection{Communication with Asterisk v1.0.x systems} + +You can set up communication with v1.0.x systems with the new jitterbuffer, but +you can't use trunks with trunktimestamps in this communication. + +If you are connecting to an Asterisk server with earlier versions of the software (1.0.x), +do not enable both jitterbuffer and trunking for the involved peers/users +in order to be able to communicate. Earlier systems will not support trunktimestamps. + +You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old +backwards compatible architecture. Look in the source code for instructions. + + +\subsubsection{Testing and monitoring} + +You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using +the new CLI command "iax2 test losspct <n>". This will simulate n percent packet loss +coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet +loss should lead to just a tiny amount of distortion, while without PLC, it would lead to +silent gaps in your audio. + +"iax2 show netstats" shows you statistics for each iax2 call you have up. +The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s +tats for both the local side (what you're receiving), and the remote side (what the other +end is telling us they are seeing). The remote stats may not be complete if the remote +end isn't using the new jitterbuffer. + +The stats shown are: +\begin{itemize} +\item Jit: The jitter we have measured (milliseconds) +\item Del: The maximum delay imposed by the jitterbuffer (milliseconds) +\item Lost: The number of packets we've detected as lost. +\item \%: The percentage of packets we've detected as lost recently. +\item Drop: The number of packets we've purposely dropped (to lower latency). +\item OOO: The number of packets we've received out-of-order +\item Kpkts: The number of packets we've received / 1000. +\end{itemize} + +\subsubsection{Reporting problems} + +There's a couple of things that can make calls sound bad using the jitterbuffer: + +\begin{enumerate} +\item The JB and PLC can make your calls sound better, but they can't fix everything. +If you lost 10 frames in a row, it can't possibly fix that. It really can't help much +more than one or two consecutive frames. + +\item Bad timestamps: If whatever is generating timestamps to be sent to you generates +nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities +in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40, +60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds +of jitter in this case, etc.. +The right solution to this is to find out what's causing the sender to send us such nonsense, +and fix that. But we should also figure out how to make the receiver more robust in +cases like this. + +chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at +some point we should try to think of a better way to detect this kind of thing and +resynchronize. + +Different clock rates are handled very gracefully though; it will actually deal with a +sender sending 20\% faster or slower than you expect just fine. + +\item Really strange network delays: If your network "pauses" for like 5 seconds, and then +when it restarts, you are sent some packets that are 5 seconds old, we are going to see +that as a lot of jitter. We already throw away up to the worst 20 frames like this, +though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case. + +\end{enumerate} diff --git a/doc/tex/localchannel.tex b/doc/tex/localchannel.tex new file mode 100644 index 000000000..76cf44566 --- /dev/null +++ b/doc/tex/localchannel.tex @@ -0,0 +1,49 @@ +\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] +\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, 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. + +\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 /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{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} + +\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} diff --git a/doc/tex/manager.tex b/doc/tex/manager.tex new file mode 100644 index 000000000..4c505ce5e --- /dev/null +++ b/doc/tex/manager.tex @@ -0,0 +1,250 @@ +\section{The Asterisk Manager TCP/IP API} + +The manager is a client/server model over TCP. With the manager interface, +you'll be able to control the PBX, originate calls, check mailbox status, +monitor channels and queues as well as execute Asterisk commands. + +AMI is the standard management interface into your Asterisk server. +You configure AMI in manager.conf. By default, AMI is available on +TCP port 5038 if you enable it in manager.conf. + +AMI receive commands, called "actions". These generate a "response" +from Asterisk. Asterisk will also send "Events" containing various +information messages about changes within Asterisk. Some actions +generate an initial response and data in the form list of events. +This format is created to make sure that extensive reports do not +block the manager interface fully. + +Management users are configured in the configuration file manager.conf and are +given permissions for read and write, where write represents their ability +to perform this class of "action", and read represents their ability to +receive this class of "event". + +If you develop AMI applications, treat the headers +in Actions, Events and Responses as local to that particular +message. There is no cross-message standardization of headers. + +If you develop applications, please try to reuse existing manager +headers and their interpretation. If you are unsure, discuss on +the asterisk-dev mailing list. + +\section{Device status reports} + +Manager subscribes to extension status reports from all channels, +to be able to generate events when an extension or device changes +state. The level of details in these events may depend on the channel +and device configuration. Please check each channel configuration +file for more information. (in sip.conf, check the section on +subscriptions and call limits) + + +\section{Command Syntax} + +Management communication consists of tags of the form "header: value", +terminated with an empty newline (\\r\\n) in the style of SMTP, HTTP, and +other headers. + +The first tag MUST be one of the following: + +\begin{itemize} + \item Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time. + \item Response: A response to an action from the Asterisk SERVER to the CLIENT. + \item Event: An event reported by the Asterisk SERVER to the CLIENT +\end{itemize} + +\section{Manager commands} + +To see all of the available manager commands, use the "manager show commands" +CLI command. + +You can get more information about a manager command +with the "manager show command <command>" CLI command in Asterisk. + +\section{Examples} +\begin{verbatim} +Login - Log a user into the manager interface. + + Action: Login + Username: testuser + Secret: testsecret + +Originate - Originate a call from a channel to an extension. + + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default + +Originate - Originate a call from a channel to an extension without waiting +for call to complete. + + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default + Async: yes + + +Redirect with ExtraChannel: + Attempted goal: + Have a 'robot' program Redirect both ends of an already-connected call + to a meetme room using the ExtraChannel feature through the management interface. + + Action: Redirect + Channel: Zap/1-1 + ExtraChannel: SIP/3064-7e00 (varies) + Exten: 680 + Priority: 1 + +Where 680 is an extension that sends you to a MeetMe room. +\end{verbatim} + +There are a number of GUI tools that use the manager interface, please search +the mailing list archives and the documentation page on the +http://www.asterisk.org web site for more information. + + +\section{Some standard AMI headers} +\begin{verbatim} + Account: -- Account Code (Status) + AccountCode: -- Account Code (cdr_manager) + ACL: <Y | N> -- Does ACL exist for object ? + Action: <action> -- request or notification of a particular action + Address-IP: -- IPaddress + Address-Port: -- IP port number + Agent: <string> -- Agent name + AMAflags: -- AMA flag (cdr_manager, sippeers) + AnswerTime: -- Time of answer (cdr_manager) + Append: <bool> -- CDR userfield Append flag + Application: -- Application to use + Async: -- Whether or not to use fast setup + AuthType: -- Authentication type (for login or challenge) + "md5" + BillableSeconds: -- Billable seconds for call (cdr_manager) + CallerID: -- Caller id (name and number in Originate & cdr_manager) + CallerID: -- CallerID number + Number or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + CallerID1: -- Channel 1 CallerID (Link event) + CallerID2: -- Channel 2 CallerID (Link event) + CallerIDName: -- CallerID name + Name or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + Callgroup: -- Call group for peer/user + CallsTaken: <num> -- Queue status variable + Cause: <value> -- Event change cause - "Expired" + Cause: <value> -- Hangupcause (channel.c) + CID-CallingPres: -- Caller ID calling presentation + Channel: <channel> -- Channel specifier + Channel: <dialstring> -- Dialstring in Originate + Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2) + Channel: <tech> -- Technology (SIP/IAX2 etc) in Registry events + ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc + Channel1: -- Link channel 1 + Channel2: -- Link channel 2 + ChanObjectType: -- "peer", "user" + Codecs: -- Codec list + CodecOrder: -- Codec order, separated with comma "," + Command: -- Cli command to run + Context: -- Context + Count: <num> -- Number of callers in queue + Data: -- Application data + Default-addr-IP: -- IP address to use before registration + Default-Username: -- Username part of URI to use before registration + Destination: -- Destination for call (Dialstring ) (dial, cdr_manager) + DestinationContext: -- Destination context (cdr_manager) + DestinationChannel: -- Destination channel (cdr_manager) + DestUniqueID: -- UniqueID of destination (dial event) + Disposition: -- Call disposition (CDR manager) + Domain: <domain> -- DNS domain + Duration: <secs> -- Duration of call (cdr_manager) + Dynamic: <Y | N> -- Device registration supported? + Endtime: -- End time stamp of call (cdr_manager) + EventList: <flag> -- Flag being "Start", "End", "Cancelled" or "ListObject" + Events: <eventmask> -- Eventmask filter ("on", "off", "system", "call", "log") + Exten: -- Extension (Redirect command) + Extension: -- Extension (Status) + Family: <string> -- ASTdb key family + File: <filename> -- Filename (monitor) + Format: <format> -- Format of sound file (monitor) + From: <time> -- Parking time (ParkedCall event) + Hint: -- Extension hint + Incominglimit: -- SIP Peer incoming limit + Key: + Key: -- ASTdb Database key + LastApplication: -- Last application executed (cdr_manager) + LastCall: <num> -- Last call in queue + LastData: -- Data for last application (cdr_manager) + Link: -- (Status) + ListItems: <number> -- Number of items in Eventlist (Optionally sent in "end" packet) + Location: -- Interface (whatever that is -maybe tech/name in app_queue ) + Loginchan: -- Login channel for agent + Logintime: <number> -- Login time for agent + Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount) + MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format + Membership: <string> -- "Dynamic" or "static" member in queue + Message: <text> -- Text message in ACKs, errors (explanation) + Mix: <bool> -- Boolean parameter (monitor) + NewMessages: <count> -- Count of new Mailbox messages (mailboxcount) + Newname: + ObjectName: -- Name of object in list + OldName: -- Something in Rename (channel.c) + OldMessages: <count> -- Count of old mailbox messages (mailboxcount) + Outgoinglimit: -- SIP Peer outgoing limit + Paused: <num> -- Queue member paused status + Peer: <tech/name> -- "channel" specifier :-) + PeerStatus: <tech/name> -- Peer status code + "Unregistered", "Registered", "Lagged", "Reachable" + Penalty: <num> -- Queue penalty + Priority: -- Extension priority + Privilege: <privilege> -- AMI authorization class (system, call, log, verbose, command, agent, user) + Pickupgroup: -- Pickup group for peer + Position: <num> -- Position in Queue + Queue: -- Queue name + Reason: -- "Autologoff" + Reason: -- "Chanunavail" + Response: <response> -- response code, like "200 OK" + "Success", "Error", "Follows" + Restart: -- "True", "False" + RegExpire: -- SIP registry expire + RegExpiry: -- SIP registry expiry + Reason: -- Originate reason code + Seconds: -- Seconds (Status) + Secret: <password> -- Authentication secret (for login) + SecretExist: <Y | N> -- Whether secret exists + Shutdown: -- "Uncleanly", "Cleanly" + SIP-AuthInsecure: + SIP-FromDomain: -- Peer FromDomain + SIP-FromUser: -- Peer FromUser + SIP-NatSupport: + SIPLastMsg: + Source: -- Source of call (dial event, cdr_manager) + SrcUniqueID: -- UniqueID of source (dial event) + StartTime: -- Start time of call (cdr_manager) + State: -- Channel state + Status: -- Registration status (Registry events SIP) + Status: -- Extension status (Extensionstate) + Status: -- Peer status (if monitored) ** Will change name ** + "unknown", "lagged", "ok" + Status: <num> -- Queue Status + Status: -- DND status (DNDState) + Time: <sec> -- Roundtrip time (latency) + Timeout: -- Parking timeout time + Timeout: -- Timeout for call setup (Originate) + Timeout: <seconds> -- Timeout for call + Uniqueid: -- Channel Unique ID + Uniqueid1: -- Channel 1 Unique ID (Link event) + Uniqueid2: -- Channel 2 Unique ID (Link event) + User: -- Username (SIP registry) + UserField: -- CDR userfield (cdr_manager) + Val: -- Value to set/read in ASTdb + Variable: -- Variable AND value to set (multiple separated with | in Originate) + Variable: <name> -- For channel variables + Value: <value> -- Value to set + VoiceMailbox: -- VM Mailbox in SIPpeers + Waiting: -- Count of mailbox messages (mailboxstatus) +\end{verbatim} + + ** Please try to re-use existing headers to simplify manager message parsing in clients. + +Read the CODING-GUIDELINES if you develop new manager commands or events. diff --git a/doc/tex/misdn.tex b/doc/tex/misdn.tex new file mode 100644 index 000000000..3b1ca17ae --- /dev/null +++ b/doc/tex/misdn.tex @@ -0,0 +1,266 @@ +\subsection{Introduction} + +This package contains the mISDN Channel Driver for the Asterisk PBX. It +supports every mISDN Hardware and provides an interface for asterisk. + +\subsection{Features} + +\begin{itemize} +\item NT and TE mode +\item PP and PMP mode +\item BRI and PRI (with BNE1 and BN2E1 Cards) +\item Hardware Bridging +\item DTMF Detection in HW+mISDNdsp +\item Display Messages on Phones (on those that support display msg) +\item app\_SendText +\item HOLD/RETRIEVE/TRANSFER on ISDN Phones : ) +\item Screen/ Not Screen User Number +\item EchoCancellation +\item Volume Control +\item Crypting with mISDNdsp (Blowfish) +\item Data (HDLC) callthrough +\item Data Calling (with app\_ptyfork +pppd) +\item Echo cancellation +\item CallDeflection +\item Some other +\end{itemize} + +\subsection{Fast Installation Guide} + +It is easy to install mISDN and mISDNuser. Just fetch the newest head of the +cvs, this can be done by: + +\begin{verbatim} +cvs -d:pserver:anonymous:readonly@cvs.isdn4linux.de:/i4ldev co mISDN mISDNuser +\end{verbatim} + +then compile and install both with: + +\begin{verbatim} +cd mISDN ; +make && make install +\end{verbatim} + +(you will need at least your kernel headers to compile mISDN). + +\begin{verbatim} +cd mISDNuser ; +make && make install +\end{verbatim} + +Now you can compile chan\_misdn, just by making asterisk: + +\begin{verbatim} +cd asterisk ; +./configure && make && make install +\end{verbatim} + +That's all! + +Follow the instructions in the mISDN Package for how to load the Kernel +Modules. + +\subsection{Pre-Requisites} + +To compile and install this driver, you'll need at least one mISDN Driver and +the mISDNuser package. Chan\_misdn works with both, the current release version +and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must +be fetched from cvs.isdn4linux.de. + +You should use Kernels >= 2.6.9 + + +\subsection{Configuration} + +First of all you must configure the mISDN drivers, please follow the +instructions in the mISDN package to do that, the main config file and config +script is: + +\begin{verbatim} +/etc/init.d/misdn-init and +/etc/misdn-init.conf +\end{verbatim} + +Now you will want to configure the misdn.conf file which resides in the +asterisk config directory (normally /etc/asterisk). + +\subsubsection{misdn.conf: [general]} +The misdn.conf file contains a "general" subsection, and user subsections which +contain misdn port settings and different Asterisk contexts. + +In the general subsection you can set options that are not directly port +related. There is for example the very important debug variable which you can +set from the Asterisk cli (command line interface) or in this configuration +file, bigger numbers will lead to more debug output. There's also a tracefile +option, which takes a path+filename where debug output is written to. + +\subsubsection{misdn.conf: [default] subsection} + +The default subsection is another special subsection which can contain all the +options available in the user/port subsections. the user/port subsection inherit +their parameters from the default subsection. + +\subsubsection{misdn.conf: user/port subsections} + +The user subsections have names which are unequal to "general". Those subsections +contain the ports variable which mean the mISDN Ports. Here you can add +multiple ports, comma separated. + +Espacially for TE-Mode Ports there is a msns option. This option tells the +chan\_misdn driver to listen for incoming calls with the given msns, you can +insert a '*' as single msn, which leads in getting every incoming call (if you +want to share on PMP TE S0 with a asterisk and a phone or isdn card you should +insert here the msns which you'll like to give the Asterisk). Finally a +context variable resides in the user subsections, which tells chan\_misdn where to +send incoming calls to in the Asterisk dial plan (extension.conf). + + +\subsubsection{Dial and Options String} + +The dial string of chan\_misdn got more complex, because we added more features, +so the generic dial string looks like: + +\begin{verbatim} +mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>] + +The Optionsstring looks Like: +:<optchar1><OptParam1>:<optchar2><OptParam2> + +the ":" character is the delimiter. + +The available Optchars are: + d - Send display text on called phone, text is the optparam + n - don't detect dtmf tones on called channel + h - make digital outgoing call + c - make crypted outgoing call, param is keyindex + e - perform echo cancellation on this channel, + takes taps as arguments (32,64,128,256) + s - send Non Inband DTMF as inband + vr - rxgain control + vt - txgain control +\end{verbatim} + +chan\_misdn registers a new dial plan application "misdn\_set\_opt" when +loaded. This application takes the Optionsstring as argument. The Syntax is: + +\begin{verbatim} +misdn_set_opt(<OPTIONSSTRING>) +\end{verbatim} + +When you set options in the dialstring, the options are set in the external +channel. When you set options with misdn\_set\_opt, they are set in the current +incoming channel. So if you like to use static encryption, the scenario looks +as follows: + +\begin{verbatim} +Phone1 --> * Box 1 --> PSTN_TE +PSTN_TE --> * Box 2 --> Phone2 +\end{verbatim} + +The Encryption must be done on the PSTN sides, so the dialplan on the boxes +are: + +\begin{verbatim} +* Box 1: +exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1) + +* Box 2: +exten => ${CRYPT_MSN},1,misdn_set_opt(:c1) +exten => ${CRYPT_MSN},2,dial(${PHONE2}) +\end{verbatim} + + +\subsection{mISDN CLI commands} + +At the Asterisk cli you can try to type in: + +\begin{verbatim} +misdn <tab> <tab> +\end{verbatim} + +Now you should see the misdn cli commands: + +\begin{verbatim} +- clean + -> pid (cleans a broken call, use with care, leads often + to a segmentation fault) +- send + -> display (sends a Text Message to a Asterisk channel, + this channel must be an misdn channel) +- set + -> debug (sets debug level) +- show + -> config (shows the configuration options) + -> channels (shows the current active misdn channels) + -> channel (shows details about the given misdn channels) + -> stacks (shows the current ports, their protocols and states) + -> fullstacks (shows the current active and inactive misdn channels) + +- restart + -> port (restarts given port (L2 Restart) ) + +- reload (reloads misdn.conf) +\end{verbatim} + +You can only use "misdn send display" when an Asterisk channel is created and +isdn is in the correct state. "correct state" means that you have established a +call to another phone (mustn't be isdn though). + +Then you use it like this: + +misdn send display mISDN/1/101 "Hello World!" + +where 1 is the Port of the Card where the phone is plugged in, and 101 is the +msn (callerid) of the Phone to send the text to. + +\subsection{mISDN Variables} + +mISDN Exports/Imports a few Variables: + +\begin{verbatim} +- MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you + can set it to 1 to force a sending complete. +\end{verbatim} + + +\subsection{Debugging and sending bug reports} + +If you encounter problems, you should set up the debugging flag, usually +debug=2 should be enough. the messages are divided in asterisk and misdn +parts. Misdn Debug messages begin with an 'I', asterisk messages begin with +an '*', the rest is clear I think. + +Please take a trace of the problem and open a report in the Asterisk issue +tracker at http://bugs.digium.com in the "channel drivers" project, +"chan\_misdn" category. Read the bug guidelines to make sure you +provide all the information needed. + + +\subsection{Examples} + +Here are some examples of how to use chan\_misdn in the dialplan +(extensions.conf): + +\begin{verbatim} +[globals] +OUT_PORT=1 ; The physical Port of the Card +OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf + +[misdnIn] +exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN}) +exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n) +\end{verbatim} + +On the last line, you will notice the last argument (Hello); this is sent +as Display Message to the Phone. + +\subsection{Known Problems} + +\begin{verbatim} +* I cannot hear any tone after a successful CONNECT to the other end + +-> you forgot to load mISDNdsp, which is now needed by chan\_misdn for switching +and dtmf tone detection +\end{verbatim} diff --git a/doc/tex/mp3.tex b/doc/tex/mp3.tex new file mode 100644 index 000000000..b1713fc1d --- /dev/null +++ b/doc/tex/mp3.tex @@ -0,0 +1,11 @@ +\subsubsection{MP3 Music On Hold} + +Use of the mpg123 for your music on hold is no longer recommended and is now +officially deprecated. You should now use one of the native formats for your +music on hold selections. + +However, if you still need to use mp3 as your music on hold format, a format +driver for reading MP3 audio files is available in the asterisk-addons SVN +repository on svn.digium.com or in the asterisk-addons release at +ftp://ftp.digium.com/pub/telephony/asterisk/. + diff --git a/doc/tex/odbcstorage.tex b/doc/tex/odbcstorage.tex new file mode 100644 index 000000000..97d1c94f1 --- /dev/null +++ b/doc/tex/odbcstorage.tex @@ -0,0 +1,29 @@ +ODBC Storage allows you to store voicemail messages within a database +instead of using a file. This is *not* a full realtime engine and +*only* supports ODBC. The table description for the "voicemessages" +table is as follows: + +\begin{verbatim} ++----------------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------+-------------+------+-----+---------+-------+ +| msgnum | int(11) | YES | | NULL | | +| dir | varchar(80) | YES | MUL | NULL | | +| context | varchar(80) | YES | | NULL | | +| macrocontext | varchar(80) | YES | | NULL | | +| callerid | varchar(40) | YES | | NULL | | +| origtime | varchar(40) | YES | | NULL | | +| duration | varchar(20) | YES | | NULL | | +| mailboxuser | varchar(80) | YES | | NULL | | +| mailboxcontext | varchar(80) | YES | | NULL | | +| recording | longblob | YES | | NULL | | ++----------------+-------------+------+-----+---------+-------+ +\end{verbatim} + +The database name (from /etc/asterisk/res\_odbc.conf) is in the +"odbcstorage" variable in the general section of voicemail.conf. + +You may modify the voicemessages table name by using +odbctable=??? in voicemail.conf. + + diff --git a/doc/tex/privacy.tex b/doc/tex/privacy.tex new file mode 100644 index 000000000..eed47644d --- /dev/null +++ b/doc/tex/privacy.tex @@ -0,0 +1,343 @@ +So, you want to avoid talking to pesky telemarketers/charity +seekers/poll takers/magazine renewers/etc? + +\subsection{First of all} + +Try the FTC "Don't call" database, this alone will reduce your +telemarketing call volume considerably. (see: +https://www.donotcall.gov/default.aspx ) But, this list won't protect +from the Charities, previous business relationships, etc. + +\subsection{Next, Fight against autodialers!!} + +Zapateller detects if callerid is present, and if not, plays the +da-da-da tones that immediately precede messages like, "I'm sorry, +the number you have called is no longer in service." + +Most humans, even those with unlisted/callerid-blocked numbers, will +not immediately slam the handset down on the hook the moment they hear +the three tones. But autodialers seem pretty quick to do this. + +I just counted 40 hangups in Zapateller over the last year in my +CDR's. So, that is possibly 40 different telemarketers/charities that have +hopefully slashed my back-waters, out-of-the-way, humble home phone +number from their lists. + +I highly advise Zapateller for those seeking the nirvana of "privacy". + + +\subsection{Next, Fight against the empty CALLERID!} + +A considerable percentage of the calls you don't want, come from +sites that do not provide CallerID. + +Null callerid's are a fact of life, and could be a friend with an +unlisted number, or some charity looking for a handout. The +PrivacyManager application can help here. It will ask the caller to +enter a 10-digit phone number. They get 3 tries(configurable), and this is +configurable, with control being passed to priority+101 if they won't +supply one. + +PrivacyManager can't guarantee that the number they supply is any +good, tho, as there is no way to find out, short of hanging up and +calling them back. But some answers are obviously wrong. For instance, +it seems a common practice for telemarketers to use your own number +instead of giving you theirs. A simple test can detect this. More +advanced tests would be to look for -555- numbers, numbers that count +up or down, numbers of all the same digit, etc. + +My logs show that 39 have hung up in the PrivacyManager script over +the last year. + +(Note: Demanding all unlisted incoming callers to enter their CID may +not always be appropriate for all users. Another option might be to +use call screening. See below.) + + +\subsection{Next, use a WELCOME MENU !} + +Experience has shown that simply presenting incoming callers with +a set of options, no matter how simple, will deter them from calling +you. In the vast majority of situations, a telemarketer will simply +hang up rather than make a choice and press a key. + +This will also immediately foil all autodialers that simply belch a +message in your ear and hang up. + +\subsubsection{Example usage of Zapateller and PrivacyManager} +\begin{verbatim} +[homeline] +exten => s,1,Answer +exten => s,2,SetVar,repeatcount=0 +exten => s,3,Zapateller,nocallerid +exten => s,4,PrivacyManager +exten => s,105,Background(tt-allbusy) ;; do this if they don't enter a number to Privacy Manager +exten => s,106,Background(tt-somethingwrong) +exten => s,107,Background(tt-monkeysintro) +exten => s,108,Background(tt-monkeys) +exten => s,109,Background(tt-weasels) +exten => s,110,Hangup +exten => s,5,GotoIf($[ "${CALLERIDNUM}" = "7773334444" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) +\end{verbatim} + +I suggest using Zapateller at the beginning of the context, before +anything else, on incoming calls.This can be followed by the +PrivacyManager App. + +Make sure, if you do the PrivacyManager app, that you take care of the +error condition! or their non-compliance will be rewarded with access +to the system. In the above, if they can't enter a 10-digit number in +3 tries, they get the humorous "I'm sorry, but all household members +are currently helping other telemarketers...", "something is terribly +wrong", "monkeys have carried them away...", various loud monkey +screechings, "weasels have...", and a hangup. There are plenty of +other paths to my torture scripts, I wanted to have some fun. + +In nearly all cases now, the telemarketers/charity-seekers that +usually get thru to my main intro, hang up. I guess they can see it's +pointless, or the average telemarketer/charity-seeker is instructed +not to enter options when encountering such systems. Don't know. + + +\subsection{Next: Torture Them!} + +I have developed an elaborate script to torture Telemarketers, and +entertain friends. (See +http://www.voip-info.org/wiki-Asterisk+Telemarketer+Torture ) + +While mostly those that call in and traverse my teletorture scripts +are those we know, and are doing so out of curiosity, there have been +these others from Jan 1st,2004 thru June 1st, 2004: +(the numbers may or may not be correct.) + +603890zzzz hung up telemarket options. +"Integrated Sale" called a couple times. hung up in telemarket options +"UNITED STATES GOV" (-- maybe a military recruiter, trying to lure one of my sons). +800349zzzz -- hung up in charity intro +800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts! +216377zzzz -- hung up the magazine section +626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices +757821zzzz -- hung up in new magazine subscription options. + +That averages out to maybe 1 a month. That puts into question whether +the ratio of the amount of labor it took to make the scripts versus +the benefits of lower call volumes was worth it, but, well, I had fun, +so what the heck. + +but, that's about it. Not a whole lot. But I haven't had to say "NO" +or "GO AWAY" to any of these folks for about a year now ...! + +\subsection{Using Call Screening} + +Another option is to use call screening in the Dial command. It has +two main privacy modes, one that remembers the CID of the caller, and +how the callee wants the call handled, and the other, which does not +have a "memory". + +Turning on these modes in the dial command results in this sequence of +events, when someone calls you at an extension: + +\begin{enumerate} +\item The caller calls the Asterisk system, and at some point, selects an +option or enters an extension number that would dial your extension. + +\item Before ringing your extension, the caller is asked to supply an +introduction. The application asks them: "After the tone, say your +name". They are allowed 4 seconds of introduction. + +\item After that, they are told "Hang on, we will attempt to connect you +to your party. Depending on your dial options, they will hear ringing +indications, or get music on hold. I suggest music on hold. + +\item Your extension is then dialed. When (and if) you pick up, you are +told that a caller presenting themselves as <their recorded intro is +played> is calling, and you have options, like being connected, +sending them to voicemail, torture, etc. + +\item You make your selection, and the call is handled as you chose. +\end{enumerate} + +There are some variations, and these will be explained in due course. + + +To use these options, set your Dial to something like: +\begin{verbatim} +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmPA(beep)) + +or + +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep)) + +or + +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep)) +\end{verbatim} + +The 't' allows the dialed party to transfer the call using '\#'. It's +optional. + +The 'm' is for music on hold. I suggest it. Otherwise, the calling +party gets to hear all the ringing, and lack thereof. It is generally +better to use Music On Hold. Lots of folks hang up after the 3rd or +4th ring, and you might lose the call before you can enter an option! + +The 'P' option alone will database everything using the extension as a +default 'tree'. To get multiple extensions sharing the same database, use +P(some-shared-key). Also, if the same person has multiple extensions, +use P(unique-id) on all their dial commands. + +Use little 'p' for screening. Every incoming call will include a +prompt for the callee's choice. + +the A(beep), will generate a 'beep' that the callee will hear if they +choose to talk to the caller. It's kind of a prompt to let the callee +know that he has to say 'hi'. It's not required, but I find it +helpful. + +When there is no CallerID, P and p options will always record an intro +for the incoming caller. This intro will be stored temporarily in the +/var/lib/asterisk/sounds/priv-callerintros dir, under the name +NOCALLERID\_<extension><channelname> and will be erased after the +callee decides what to do with the call. + +Of course, NOCALLERID is not stored in the database. All those with no +CALLERID will be considered "Unknown". + +\subsection{The 'N' and 'n' options} + +Two other options exist, that act as modifiers to the privacy options +'P' and 'p'. They are 'N' and 'n'. You can enter them as dialing +options, but they only affect things if P or p are also in the +options. + +'N' says, "Only screen the call if no CallerID is present". So, if a +callerID were supplied, it will come straight thru to your extension. + +'n' says, "Don't save any introductions". Folks will be asked to +supply an introduction ("At the tone, say your name") every time they +call. Their introductions will be removed after the callee makes a +choice on how to handle the call. Whether the P option or the p option +is used, the incoming caller will have to supply their intro every +time they call. + + +\subsection{Recorded Introductions} + +\subsubsection{Philosophical Side Note} +The 'P' option stores the CALLERID in the database, along with the +callee's choice of actions, as a convenience to the CALLEE, whereas +introductions are stored and re-used for the convenience of the CALLER.] + +\subsubsection{Introductions} +Unless instructed to not save introductions (see the 'n' option above), +the screening modes will save the recordings of the caller's names in +the directory /var/lib/asterisk/sounds/priv-callerintros, if they have +a CallerID. Just the 10-digit callerid numbers are used as filenames, +with a ".gsm" at the end. + +Having these recordings around can be very useful, however... + +First of all, if a callerid is supplied, and a recorded intro for that +number is already present, the caller is spared the inconvenience of +having to supply their name, which shortens their call a bit. + +Next of all, these intros can be used in voicemail, played over +loudspeakers, and perhaps other nifty things. For instance: + +\begin{verbatim} +exten => s,7,System(/usr/bin/play /var/lib/asterisk/sounds/priv-callerintros/${CALLERIDNUM}.gsm&|0) +\end{verbatim} + +When a call comes in at the house, the above priority gets executed, +and the callers intro is played over the phone systems speakers. This +gives us a hint who is calling. + +(Note: the |0 option at the end of the System command above, is a +local mod I made to the System command. It forces a 0 result code to +be returned, whether the play command successfully completed or +not. Therefore, I don't have to ensure that the file exists or +not. While I've turned this mod into the developers, it hasn't been +incorporated yet. You might want to write an AGI or shell script to +handle it a little more intelligently) + +And one other thing. You can easily supply your callers with an option +to listen to, and re-record their introductions. Here's what I did in +the home system's extensions.conf. (assume that a +Goto(home-introduction|s|1) exists somewhere in your main menu as an +option): + +\begin{verbatim} +[home-introduction] +exten => s,1,Background,intro-options ;; Script: To hear your Introduction, dial 1. + ;; to record a new introduction, dial 2. + ;; to return to the main menu, dial 3. + ;; to hear what this is all about, dial 4. +exten => 1,1,Playback,priv-callerintros/${CALLERIDNUM} +exten => 1,2,Goto(s,1) +exten => 2,1,Goto(home-introduction-record,s,1) +exten => 3,1,Goto(homeline,s,7) +exten => 4,1,Playback,intro-intro ;; Script: + ;; This may seem a little strange, but it really is a neat + ;; thing, both for you and for us. I've taped a short introduction + ;; for many of the folks who normally call us. Using the Caller ID + ;; from each incoming call, the system plays the introduction + ;; for that phone number over a speaker, just as the call comes in. + ;; This helps the folks + ;; here in the house more quickly determine who is calling. + ;; and gets the right ones to gravitate to the phone. + ;; You can listen to, and record a new intro for your phone number + ;; using this menu. +exten => 4,2,Goto(s,1) +exten => t,1,Goto(s,1) +exten => i,1,Background,invalid +exten => i,2,Goto(s,1) +exten => o,1,Goto(s,1) + +[home-introduction-record] +exten => s,1,Background,intro-record-choices ;; Script: + ;; If you want some advice about recording your + ;; introduction, dial 1. + ;; otherwise, dial 2, and introduce yourself after + ;; the beep. +exten => 1,1,Playback,intro-record + ;; Your introduction should be short and sweet and crisp. + ;; Your introduction will be limited to 4 seconds. + ;; This is NOT meant to be a voice mail message, so + ;; please, don't say anything about why you are calling. + ;; After we are done making the recording, your introduction + ;; will be saved for playback. + ;; If you are the only person that would call from this number, + ;; please state your name. Otherwise, state your business + ;; or residence name instead. For instance, if you are + ;; friend of the family, say, Olie McPherson, and both + ;; you and your kids might call here a lot, you might + ;; say: "This is the distinguished Olie McPherson Residence!" + ;; If you are the only person calling, you might say this: + ;; "This is the illustrious Kermit McFrog! Pick up the Phone, someone!!" + ;; If you are calling from a business, you might pronounce a more sedate introduction,like, + ;; "Fritz from McDonalds calling.", or perhaps the more original introduction: + ;; "John, from the Park County Morgue. You stab 'em, we slab 'em!". + ;; Just one caution: the kids will hear what you record every time + ;; you call. So watch your language! + ;; I will begin recording after the tone. + ;; When you are done, hit the # key. Gather your thoughts and get + ;; ready. Remember, the # key will end the recording, and play back + ;; your intro. Good Luck, and Thank you!" +exten => 1,2,Goto(2,1) +exten => 2,1,Background,intro-start + ;; OK, here we go! After the beep, please give your introduction. +exten => 2,2,Background,beep +exten => 2,3,Record,priv-callerintros/${CALLERIDNUM}:gsm|4 +exten => 2,4,Background,priv-callerintros/${CALLERIDNUM} +exten => 2,5,Goto(home-introduction,s,1) +exten => t,1,Goto(s,1) +exten => i,1,Background,invalid +exten => i,2,Goto(s,1) +exten => o,1,Goto(s,1) +\end{verbatim} + +In the above, you'd most likely reword the messages to your liking, +and maybe do more advanced things with the 'error' conditions (i,o,t priorities), +but I hope it conveys the idea. + + diff --git a/doc/tex/qos.tex b/doc/tex/qos.tex new file mode 100644 index 000000000..b86107fe5 --- /dev/null +++ b/doc/tex/qos.tex @@ -0,0 +1,119 @@ +\subsubsection{Introduction} + +Asterisk can set the Type of Service (TOS) byte on outgoing IP packets +for various protocols. The TOS byte is used by the network to provide +some level of Quality of Service (QoS) even if the network is +congested with other traffic. + +Also asterisk running on Linux can set 802.1p CoS marks in VLAN packets +for all used VoIP protocols. It is useful when you are working in switched +enviropment. For maping skb->priority and VLAN CoS mark you need to use +command "vconfig set\_egress\_map [vlan-device] [skb-priority] [vlan-qos]". + +\subsubsection{SIP} + +In sip.conf, there are three parameters that control the TOS settings: +"tos\_sip", "tos\_audio" and "tos\_video". tos\_sip controls what TOS SIP +call signalling packets are set to. tos\_audio controls what TOS RTP audio +packets are set to. tos\_video controls what TOS RTP video packets are +set to. + +There are four parameters to control 802.1p CoS: "cos\_sip", "cos\_audio", +"cos\_video" and "cos\_text". It's behavior the same as writen above. + +There is a "tos" parameter that is supported for backwards +compatibility. The tos parameter should be avoided in sip.conf +because it sets all three tos settings in sip.conf to the same value. + +\subsubsection{IAX2} +In iax.conf, there is a "tos" parameter that sets the global default TOS +for IAX packets generated by chan\_iax2. Since IAX connections combine +signalling, audio, and video into one UDP stream, it is not possible +to set the TOS separately for the different types of traffic. + +In iaxprov.conf, there is a "tos" parameter that tells the IAXy what TOS +to set on packets it generates. As with the parameter in iax.conf, +IAX packets generated by an IAXy cannot have different TOS settings +based upon the type of packet. However different IAXy devices can +have different TOS settings. + +\subsubsection{H.323} +Also support TOS and CoS. + +\subsubsection{MGCP} +Also support TOS and CoS. + +\subsubsection{IP TOS values} + +The allowable values for any of the tos* parameters are: +CS0, CS1, CS2, CS3, CS4, CS5, CS6, CS7, AF11, AF12, AF13, +AF21, AF22, AF23, AF31, AF32, AF33, AF41, AF42, AF43 and +ef (expedited forwarding), + +The tos* parameters also take numeric values. + +The lowdelay, throughput, reliability, mincost, and none values are +deprecated because they set the IP TOS using the outdated "IP +precedence" model as defined in RFC 791 and RFC 1349. They still +work in this version of Asterisk, but will be removed in future releases. + +\subsubsection{802.1p CoS values} + +As 802.1p uses 3 bites from VLAN header, there are parameter can take +integer values from 0 to 7. + + +\begin{verbatim} +=========================================== +Configuration Parameter Recommended +File Setting +------------------------------------------- +sip.conf tos\_sip cs3 +sip.conf tos\_audio ef +sip.conf tos\_video af41 +sip.conf tos\_text af41 +sip.conf cos\_sip 4 +sip.conf cos\_audio 6 +sip.conf cos\_video 5 +sip.conf cos\_text 0 +------------------------------------------- +iax.conf tos ef +iax.conf cos 6 +------------------------------------------- +iaxprov.conf tos ef +------------------------------------------- +mgcp.conf tos ef +mgcp.conf cos 6 +------------------------------------------- +h323.conf tos ef +h323.conf cos 6 +=========================================== +\end{verbatim} + +\subsubsection{Reference} + +IEEE 802.1Q Standard: +http://standards.ieee.org/getieee802/download/802.1Q-1998.pdf +Related protocols: IEEE 802.3, 802.2, 802.1D, 802.1Q + +RFC 2474 - "Definition of the Differentiated Services Field +(DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al, +December 1998. + +IANA Assignments, DSCP registry +Differentiated Services Field Codepoints +http://www.iana.org/assignments/dscp-registry + +To get the most out of setting the TOS on packets generated by +Asterisk, you will need to ensure that your network handles packets +with a TOS properly. For Cisco devices, see the previously mentioned +"Enterprise QoS Solution Reference Network Design Guide". For Linux +systems see the "Linux Advanced Routing \& Traffic Control HOWTO" at +<http://www.lartc.org/>. + +For more information on Quality of +Service for VoIP networks see the "Enterprise QoS Solution Reference +Network Design Guide" version 3.3 from Cisco at: + +<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration\_09186a008049b062.pdf> + diff --git a/doc/tex/queuelog.tex b/doc/tex/queuelog.tex new file mode 100644 index 000000000..dd2047af6 --- /dev/null +++ b/doc/tex/queuelog.tex @@ -0,0 +1,99 @@ +In order to properly manage ACD queues, it is important to be able to +keep track of details of call setups and teardowns in much greater detail +than traditional call detail records provide. In order to support this, +extensive and detailed tracing of every queued call is stored in the +queue log, located (by default) in /var/log/asterisk/queue\_log. + +These are the events (and associated information) in the queue log: + +ABANDON(position|origposition|waittime) +The caller abandoned their position in the queue. The position is the +caller's position in the queue when they hungup, the origposition is +the original position the caller was when they first entered the +queue, and the waittime is how long the call had been waiting in the +queue at the time of disconnect. + +AGENTDUMP +The agent dumped the caller while listening to the queue announcement. + +AGENTLOGIN(channel) +The agent logged in. The channel is recorded. + +AGENTCALLBACKLOGIN(exten@context) +The callback agent logged in. The login extension and context is recorded. + +AGENTLOGOFF(channel|logintime) +The agent logged off. The channel is recorded, along with the total time +the agent was logged in. + +AGENTCALLBACKLOGOFF(exten@context|logintime|reason) +The callback agent logged off. The last login extension and context is +recorded, along with the total time the agent was logged in, and the +reason for the logoff if it was not a normal logoff +(e.g., Autologoff, Chanunavail) + +COMPLETEAGENT(holdtime|calltime|origposition) +The caller was connected to an agent, and the call was terminated normally +by the *agent*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +COMPLETECALLER(holdtime|calltime|origposition) +The caller was connected to an agent, and the call was terminated normally +by the *caller*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +CONFIGRELOAD +The configuration has been reloaded (e.g. with asterisk -rx reload) + +CONNECT(holdtime|bridgedchanneluniqueid) +The caller was connected to an agent. Hold time represents the amount +of time the caller was on hold. The bridged channel unique ID contains +the unique ID of the queue member channel that is taking the call. This +is useful when trying to link recording filenames to a particular +call in the queue. + +ENTERQUEUE(url|callerid) +A call has entered the queue. URL (if specified) and Caller*ID are placed +in the log. + +EXITEMPTY(position|origposition|waittime) +The caller was exited from the queue forcefully because the queue had no +reachable members and it's configured to do that to callers when there +are no reachable members. The position is the caller's position in the +queue when they hungup, the origposition is the original position the +caller was when they first entered the queue, and the waittime is how +long the call had been waiting in the queue at the time of disconnect. + +EXITWITHKEY(key|position|origposition|waittime) +The caller elected to use a menu key to exit the queue. The key and +the caller's position in the queue are recorded. The caller's entry +position and amoutn of time waited is also recorded. + +EXITWITHTIMEOUT(position|origposition|waittime) +The caller was on hold too long and the timeout expired. The position in the +queue when the timeout occurred, the entry position, and the amount of time +waited are logged. + +QUEUESTART +The queueing system has been started for the first time this session. + +RINGNOANSWER(ringtime) +After trying for ringtime ms to connect to the available queue member, +the attempt ended without the member picking up the call. Bad queue +member! + +SYSCOMPAT +A call was answered by an agent, but the call was dropped because the +channels were not compatible. + +TRANSFER(extension|context|holdtime|calltime) +Caller was transferred to a different extension. Context and extension +are recorded. The caller's hold time and the length of the call are both +recorded. PLEASE remember that transfers performed by SIP UA's by way +of a reinvite may not always be caught by Asterisk and trigger off this +event. The only way to be 100\% sure that you will get this event when +a transfer is performed by a queue member is to use the built-in transfer +functionality of Asterisk. + diff --git a/doc/tex/queues-with-callback-members.tex b/doc/tex/queues-with-callback-members.tex new file mode 100644 index 000000000..b1a7d8fd2 --- /dev/null +++ b/doc/tex/queues-with-callback-members.tex @@ -0,0 +1,535 @@ + +\section{Introduction} + +Pardon, but the dialplan in this tutorial will be expressed +in AEL, the new Asterisk Extension Language. If you are +not used to its syntax, we hope you will find it to some +degree intuitive. If not, there are documents explaining +its syntax and constructs. + + +\section{Configuring Call Queues} + +\subsection{queues.conf} +First of all, set up call queues in queue.conf + +Here is an example: + +\begin{verbatim} + =========== queues.conf =========== + | ; Cool Digium Queues | + | [general] | + | persistentmembers = yes | + | | + | ; General sales queue | + | [sales-general] | + | music=default | + | context=sales | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Customer service queue | + | [customerservice] | + | music=default | + | context=customerservice | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Support dispatch queue | + | [dispatch] | + | music=default | + | context=dispatch | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + =================================== +\end{verbatim} + +In the above, we have defined 3 separate calling queues: +sales-general, customerservice, and dispatch. + +Please note that the sales-general queue specifies a +context of "sales", and that customerservice specifies the +context of "customerservice", and the dispatch +queue specifies the context "dispatch". These three +contexts must be defined somewhere in your dialplan. +We will show them after the main menu below. + +<verbage explaining options above> +In the [general] section, specifying the persistentmembers=yes, +will cause the agent lists to be stored in astdb, and +recalled on startup. + +The strategy=ringall will cause all agents to be dialed +together, the first to answer is then assigned the incoming +call. + +"joinempty" set to "strict" will keep incoming callers from +being placed in queues where there are no agents to take calls. +The Queue() application will return, and the dial plan can +determine what to do next. + +If there are calls queued, and the last agent logs out, the +remaining incoming callers will immediately be removed from +the queue, and the Queue() call will return, IF the "leavewhenempty" is +set to "strict". + +\subsection{Routing incoming Calls to Queues} + + +Then in extensions.ael, you can do these things: + +\subsubsection{The Main Menu} + +At Digium, incoming callers are sent to the "mainmenu" context, where they +are greeted, and directed to the numbers they choose... + +\begin{verbatim} +context mainmenu { + + includes { + digium; + queues-loginout; + } + + 0 => goto dispatch|s|1; + 2 => goto sales|s|1; + 3 => goto customerservice|s|1; + 4 => goto dispatch|s|1; + + s => { + Ringing(); + Wait(1); + Set(attempts=0); + Answer(); + Wait(1); + Background(digium/ThankYouForCallingDigium); + Background(digium/YourOpenSourceTelecommunicationsSupplier); + WaitExten(0.3); + repeat: + Set(attempts=$[${attempts} + 1]); + Background(digium/IfYouKnowYourPartysExtensionYouMayDialItAtAnyTime); + WaitExten(0.1); + Background(digium/Otherwise); + WaitExten(0.1); + Background(digium/ForSalesPleasePress2); + WaitExten(0.2); + Background(digium/ForCustomerServicePleasePress3); + WaitExten(0.2); + Background(digium/ForAllOtherDepartmentsPleasePress4); + WaitExten(0.2); + Background(digium/ToSpeakWithAnOperatorPleasePress0AtAnyTime); + if( ${attempts} < 2 ) { + WaitExten(0.3); + Background(digium/ToHearTheseOptionsRepeatedPleaseHold); + } + WaitExten(5); + if( ${attempts} < 2 ) goto repeat; + Background(digium/YouHaveMadeNoSelection); + Background(digium/ThisCallWillBeEnded); + Background(goodbye); + Hangup(); + } +} +\end{verbatim} + +\subsubsection{The Contexts referenced from the queues.conf file} + +\begin{verbatim} +context sales { + + 0 => goto dispatch|s|1; + 8 => Voicemail(${SALESVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForContactingTheDigiumSalesDepartment); + WaitExten(0.3); + Background(digium/PleaseHoldAndYourCallWillBeAnsweredByOurNextAvailableSalesRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Sales); + Queue(sales-general|t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch|s|1; + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} + +Please note that there is only one attempt to queue a call in the sales queue. All sales agents that +are logged in will be rung. + +\begin{verbatim} +context customerservice { + + 0 => { + SetCIDName(CSVTrans); + goto dispatch|s|1; + } + 8 => Voicemail(${CUSTSERVVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigiumCustomerService); + WaitExten(0.3); + notracking: + Background(digium/PleaseWaitForTheNextAvailableCustomerServiceRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Cust Svc); + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice|t); + Set(CALLERID(name)=EmptyCSVQ); + goto dispatch|s|1; + Background(digium/NoCustomerServiceRepresentativesAreAvailableAtThisTime); + Background(digium/PleaseLeaveAMessageInTheCustomerServiceVoiceMailBox); + Voicemail(${CUSTSERVVM}); + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} + +Note that calls coming into customerservice will first be try to queue +calls to those agents with a QUEUE\_MAX\_PENALTY of 10, and if none are available, +then all agents are rung. + +\begin{verbatim} +context dispatch +{ + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigium); + WaitExten(0.3); + Background(digium/YourCallWillBeAnsweredByOurNextAvailableOperator); + Background(digium/PleaseHold); + Set(QUEUE_MAX_PENALTY=10); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=20); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(dispatch|t); + Background(digium/NoOneIsAvailableToTakeYourCall); + Background(digium/PleaseLeaveAMessageInOurGeneralVoiceMailBox); + Voicemail(${DISPATCHVM}); + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} + +And in the dispatch context, first agents of priority 10 are tried, then +20, and if none are available, all agents are tried. + +Notice that a common pattern is followed in each of the three queue contexts: + +First, you set QUEUE\_MAX\_PENALTY to a value, then you call +Queue(<queue-name>,option,... (see the documentation for the Queue application)); + +In the above, note that the "t" option is specified, and this allows the +agent picking up the incoming call the luxury of transferring the call to +other parties. + +The purpose of specifying the QUEUE\_MAX\_PENALTY is to develop a set of priorities +amongst agents. By the above usage, agents with lower number priorities will +be given the calls first, and then, if no-one picks up the call, the QUEUE\_MAX\_PENALTY +will be incremented, and the queue tried again. Hopefully, along the line, someone +will pick up the call, and the Queue application will end with a hangup. + +The final attempt to queue in most of our examples sets the QUEUE\_MAX\_PENALTY +to zero, which means to try all available agents. + + +\subsection{Assigning agents to Queues} + +In this example dialplan, we want to be able to add and remove agents to +handle incoming calls, as they feel they are available. As they log in, +they are added to the queue's agent list, and as they log out, they are +removed. If no agents are available, the queue command will terminate, and +it is the duty of the dialplan to do something appropriate, be it sending +the incoming caller to voicemail, or trying the queue again with a higher +QUEUE\_MAX\_PENALTY. + +Because a single agent can make themselves available to more than one queue, +the process of joining multiple queues can be handled automatically by the +dialplan. + +\subsubsection{Agents Log In and Out} + +\begin{verbatim} +context queues-loginout +{ + 6092 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + VMAuthenticate(${AGENT_NUMBER}@default,s); + Set(queue-announce-success=1); + goto queues-manip,I${AGENT_NUMBER},1; + } + + 6093 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + Set(queue-announce-success=1); + goto queues-manip,O${AGENT_NUMBER},1; + } +} +\end{verbatim} + +In the above contexts, the agents dial 6092 to log into their queues, +and they dial 6093 to log out of their queues. The agent is prompted +for their agent number, and if they are logging in, their passcode, +and then they are transferred to the proper extension in the +queues-manip context. The queues-manip context does all the +actual work: + +\begin{verbatim} +context queues-manip { + + // Raquel Squelch + _[IO]6121 => { + &queue-addremove(dispatch,10,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Brittanica Spears + _[IO]6165 => { + &queue-addremove(dispatch,20,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Rock Hudson + _[IO]6170 => { + &queue-addremove(sales-general,10,${EXTEN}); + &queue-addremove(customerservice,20,${EXTEN}); + &queue-addremove(dispatch,30,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Saline Dye-on + _[IO]6070 => { + &queue-addremove(sales-general,20,${EXTEN}); + &queue-addremove(customerservice,30,${EXTEN}); + &queue-addremove(dispatch,30,${EXTEN}); + &queue-success(${EXTEN}); + } +} +\end{verbatim} + +In the above extensions, note that the queue-addremove macro is used +to actually add or remove the agent from the applicable queue, +with the applicable priority level. Note that agents with a +priority level of 10 will be called before agents with levels +of 20 or 30. + +In the above example, Raquel will be dialed first in the dispatch +queue, if she has logged in. If she is not, then the second call of +Queue() with priority of 20 will dial Brittanica if she is present, +otherwise the third call of Queue() with MAX\_PENALTY of 0 will +dial Rock and Saline simultaneously. + +Also note that Rock will be among the first to be called in the sales-general +queue, and among the last in the dispatch queue. As you can see in +main menu, the callerID is set in the main menu so they can tell +which queue incoming calls are coming from. + +The call to queue-success() gives some feedback to the agent +as they log in and out, that the process has completed. + +\begin{verbatim} +macro queue-success(exten) +{ + if( ${queue-announce-success} > 0 ) + { + switch(${exten:0:1}) + { + case I: + Playback(agent-loginok); + Hangup(); + case O: + Playback(agent-loggedoff); + Hangup(); + } + } +} +\end{verbatim} + +The queue-addremove macro is defined in this manner: + +\begin{verbatim} +macro queue-addremove(queuename,penalty,exten) +{ + switch(${exten:0:1}) + { + case I: // Login + { + AddQueueMember(${queuename},Local/${exten:1}@agents,${penalty}); + break; + } + case O: // Logout + { + RemoveQueueMember(${queuename},Local/${exten:1}@agents); + break; + } + case P: // Pause + { + PauseQueueMember(${queuename},Local/${exten:1}@agents); + break; + } + case U: // Unpause + { + UnpauseQueueMember(${queuename},Local/${exten:1}@agents); + break; + } + default: // Invalid + { + Playback(invalid); + } + } +} +\end{verbatim} + +Basically, it uses the first character of the exten variable, to determine the +proper actions to take. In the above dial plan code, only the cases I or O are used, +which correspond to the Login and Logout actions. + + +\subsection{Controlling The Way Queues Call the Agents} + +Notice in the above, that the commands to manipulate agents in queues have +"@agents" in their arguments. This is a reference to the agents context: + +\begin{verbatim} +context agents +{ + // General sales queue + 8010 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(sales-general|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(sales-general|t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch|s|1; + } + // Customer Service queue + 8011 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice|t); + Set(CALLERID(name)=EMptyCSVQ); + goto dispatch|s|1; + } + 8013 => + { + Dial(iax2/sweatshop/9456@from-ecstacy); + + Set(CALLERID(name)=EmptySupQ); + Set(QUEUE_MAX_PENALTY=10); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=20); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=0); // means no max + Queue(support-dispatch,t); + goto dispatch|s|1; + } + 6121 => &callagent(${RAQUEL},${EXTEN}); + 6165 => &callagent(${SPEARS},${EXTEN}); + 6170 => &callagent(${ROCK},${EXTEN}); + 6070 => &callagent(${SALINE},${EXTEN}); +} +\end{verbatim} + +In the above, the variables \${RAQUEL}, etc stand for +actual devices to ring that person's +phone (like Zap/37). + +The 8010, 8011, and 8013 extensions are purely for transferring +incoming callers to queues. For instance, a customer service +agent might want to transfer the caller to talk to sales. The +agent only has to transfer to extension 8010, in this case. + +Here is the callagent macro, note that if a person in the +queue is called, but does not answer, then they are automatically +removed from the queue. + +\begin{verbatim} +macro callagent(device,exten) +{ + if( ${GROUP_COUNT(${exten}@agents)}=0 ) + { + Set(OUTBOUND_GROUP=${exten}@agents); + Dial(${device}|300|t); + switch(${DIALSTATUS}) + { + case BUSY: + Busy(); + break; + case NOANSWER: + Set(queue-announce-success=0); + goto queues-manip|O${exten}|1; + default: + Hangup(); + break; + } + } + else + { + Busy(); + } +} +\end{verbatim} + +In the callagent macro above, the \${exten} will +be 6121, or 6165, etc, which is the extension of the agent. + +The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line +of thinking. Incoming calls can be queued to ring all agents in the +current priority. If some of those agents are already talking, they +would get bothersome call-waiting tones. To avoid this inconvenience, +when an agent gets a call, the OUTBOUND\_GROUP assigns that +conversation to the group specified, for instance 6171@agents. +The \${GROUP\_COUNT()} variable on a subsequent call should return +"1" for that group. If GROUP\_COUNT returns 1, then the busy() +is returned without actually trying to dial the agent. + +\subsection{Pre Acknowledgement Message} + +If you would like to have a pre acknowledge message with option to reject the message +you can use the following dialplan Macro as a base with the 'M' dial argument. + +\begin{verbatim} +[macro-screen] +exten=>s,1,Wait(.25) +exten=>s,2,Read(ACCEPT|screen-callee-options|1) +exten=>s,3,Gotoif($[${ACCEPT} = 1] ?50) +exten=>s,4,Gotoif($[${ACCEPT} = 2] ?30) +exten=>s,5,Gotoif($[${ACCEPT} = 3] ?40) +exten=>s,6,Gotoif($[${ACCEPT} = 4] ?30:30) +exten=>s,30,Set(MACRO_RESULT=CONTINUE) +exten=>s,40,Read(TEXTEN|custom/screen-exten|) +exten=>s,41,Gotoif($[${LEN(${TEXTEN})} = 3]?42:45) +exten=>s,42,Set(MACRO_RESULT=GOTO:from-internal^${TEXTEN}^1) +exten=>s,45,Gotoif($[${TEXTEN} = 0] ?46:4) +exten=>s,46,Set(MACRO_RESULT=CONTINUE) +exten=>s,50,Playback(after-the-tone) +exten=>s,51,Playback(connected) +exten=>s,52,Playback(beep) +\end{verbatim} + +\subsection{Caveats} + +In the above examples, some of the possible error checking has been omitted, +to reduce clutter and make the examples clearer. diff --git a/doc/tex/realtime.tex b/doc/tex/realtime.tex new file mode 100644 index 000000000..c08dbc8a5 --- /dev/null +++ b/doc/tex/realtime.tex @@ -0,0 +1,130 @@ +\subsubsection{Introduction} + +The Asterisk Realtime Architecture is a new set of drivers and +functions implemented in Asterisk. + +The benefits of this architecture are many, both from a code management +standpoint and from an installation perspective. + +Additional information on the configuration of Realtime with Asterisk +can be found in doc/extconfig.txt + +The ARA is designed to be independent of storage. Currently, most +drivers are based on SQL, but the architecture should be able to handle +other storage methods in the future, like LDAP. + +The main benefit comes in the database support. In Asterisk v1.0 some +functions supported MySQL database, some PostgreSQL and other ODBC. +With the ARA, we have a unified database interface internally in Asterisk, +so if one function supports database integration, all databases that has a +realtime driver will be supported in that function. + +Currently there are three realtime database drivers: + +\begin{itemize} + \item ODBC: Support for UnixODBC, integrated into Asterisk + The UnixODBC subsystem supports many different databases, + please check www.unixodbc.org for more information. + \item MySQL: Found in the asterisk-addons subversion repository on svn.digium.com + \item PostgreSQL: Native support for Postgres, integrated into Asterisk +\end{itemize} + +\subsubsection{Two modes: Static and Realtime} + +The ARA realtime mode is used to dynamically load and update objects. +This mode is used in the SIP and IAX2 channels, as well as in the voicemail +system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS +functionality. With the ARA, we now support many more databases for +dynamic configuration of phones. + +The ARA static mode is used to load configuration files. For the Asterisk +modules that read configurations, there's no difference between a static +file in the file system, like extensions.conf, and a configuration loaded +from a database. + +\subsubsection{Realtime SIP friends} + +The SIP realtime objects are users and peers that are loaded in memory +when needed, then deleted. This means that Asterisk currently can't handle +voicemail notification and NAT keepalives for these peers. Other than that, +most of the functionality works the same way for realtime friends as for +the ones in static configuration. + +With caching, the device stays in memory for a specified time. More +information about this is to be found in the sip.conf sample file. + +\subsubsection{Realtime H.323 friends} + +Like SIP realtime friends, H.323 friends also can be configured using +dynamic realtime objects. + +\subsubsection{New function in the dial plan: The Realtime Switch} + +The realtime switch is more than a port of functionality in v1.0 to the +new architecture, this is a new feature of Asterisk based on the +ARA. The realtime switch lets your Asterisk server do database lookups +of extensions in realtime from your dial plan. You can have many Asterisk +servers sharing a dynamically updated dial plan in real time with this +solution. + +Note that this switch does NOT support Caller ID matching, only +extension name or pattern matching. + +\subsubsection{Capabilities} + +The realtime Architecture lets you store all of your configuration in +databases and reload it whenever you want. You can force a reload over +the AMI, Asterisk Manager Interface or by calling Asterisk from a +shell script with + + asterisk -rx "reload" + +You may also dynamically add SIP and IAX devices and extensions +and making them available without a reload, by using the realtime +objects and the realtime switch. + +\subsubsection{Configuration in extconfig.conf} + +You configure the ARA in extconfig.conf (yes, it's a strange name, but +is was defined in the early days of the realtime architecture and kind +of stuck). Please see doc/extconfig.txt for database schemas. + +The part of Asterisk that connects to the ARA use a well defined family +name to find the proper database driver. The syntax is easy: + +\begin{verbatim} + <family> => <realtime driver>,<db name>[,<table>] +\end{verbatim} + +The options following the realtime driver identified depends on the +driver. + +Defined well-known family names are: + +\begin{itemize} + \item sippeers, sipusers - SIP peers and users + \item iaxpeers, iaxusers - IAX2 peers and users + \item voicemail - Voicemail accounts + \item queues - Queues + \item queue\_members - Queue members + \item extensions - Realtime extensions (switch) +\end{itemize} + +There is documentation of the SQL database in the file +doc/extconfig.txt in your Asterisk source code tree. + +For voicemail storage with the support of ODBC, there is a +doc/odbcstorage.txt documentation file. + +\subsubsection{Limitations} + +Currently, realtime extensions do not support realtime hints. There is +a workaround available by using func\_odbc. See the sample func\_odbc.conf +for more information. + +\subsubsection{FreeTDS supported with connection pooling} + +In order to use a FreeTDS-based database with realtime, you need to turn +connection pooling on in res\_odbc.conf. This is due to a limitation within +the FreeTDS protocol itself. Please note that this includes databases such +as MS SQL Server and Sybase. This support is new in the current release. diff --git a/doc/tex/security.tex b/doc/tex/security.tex new file mode 100644 index 000000000..188f42cab --- /dev/null +++ b/doc/tex/security.tex @@ -0,0 +1,76 @@ +\subsection{Introduction} + +PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. +IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR +FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES. + +Asterisk security involves both network security (encryption, authentication) +as well as dialplan security (authorization - who can access services in +your pbx). If you are setting up Asterisk in production use, please make +sure you understand the issues involved. + +\subsection{Network Security} + +If you install Asterisk and use the "make samples" command to install +a demonstration configuration, Asterisk will open a few ports for accepting +VoIP calls. Check the channel configuration files for the ports and IP addresses. + +If you enable the manager interface in manager.conf, please make sure that +you access manager in a safe environment or protect it with SSH or other +VPN solutions. + +For all TCP/IP connections in Asterisk, you can set ACL lists that +will permit or deny network access to Asterisk services. Please check +the "permit" and "deny" configuration options in manager.conf and +the VoIP channel configurations - i.e. sip.conf and iax.conf. + +The IAX2 protocol supports strong RSA key authentication as well as +AES encryption of voice and signalling. The SIP channel does not +support encryption in this version of Asterisk. + +\subsection{Dialplan Security} + +First and foremost remember this: + +USE THE EXTENSION CONTEXTS TO ISOLATE OUTGOING OR TOLL SERVICES FROM ANY +INCOMING CONNECTIONS. + +You should consider that if any channel, incoming line, etc can enter an +extension context that it has the capability of accessing any extension +within that context. + +Therefore, you should NOT allow access to outgoing or toll services in +contexts that are accessible (especially without a password) from incoming +channels, be they IAX channels, FX or other trunks, or even untrusted +stations within you network. In particular, never ever put outgoing toll +services in the "default" context. To make things easier, you can include +the "default" context within other private contexts by using: + +\begin{verbatim} + include => default +\end{verbatim} + +in the appropriate section. A well designed PBX might look like this: + +\begin{verbatim} +[longdistance] +exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => local + +[local] +exten => _9NXXNXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => default + +[default] +exten => 6123,Dial(Zap/1) +\end{verbatim} + +DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There +isn't really a security reason, it just will keep people from wanting to +play with your Asterisk setup remotely. + +\subsection{Log Security} + +Please note that the Asterisk log files, as well as information printed to the +Asterisk CLI, may contain sensitive information such as passwords and call +history. Keep this in mind when providing access to these resources. diff --git a/doc/tex/sla.tex b/doc/tex/sla.tex new file mode 100644 index 000000000..efcd6b43f --- /dev/null +++ b/doc/tex/sla.tex @@ -0,0 +1,378 @@ +%\documentclass[12pt,a4]{article} +%\usepackage{hyperref} + +%\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.} +%\title{Shared Line Appearances} + +%\begin{document} +%\maketitle + +%\tableofcontents + +\section{Introduction} + +The "SLA" functionality in Asterisk is intended to allow a setup that emulates +a simple key system. It uses the various abstraction layers already built into +Asterisk to emulate key system functionality across various devices, including +IP channels. + +\section{Configuration} + +\subsection{Summary} + +An SLA system is built up of virtual trunks and stations mapped to real +Asterisk devices. The configuration for all of this is done in three +different files: extensions.conf, sla.conf, and the channel specific +configuration file such as sip.conf or zapata.conf. + +\subsection{Dialplan} + +The SLA implementation can automatically generate the dialplan necessary for +basic operation if the "autocontext" option is set for trunks and stations in +sla.conf. However, for reference, here is an automatically generated dialplan +to help with custom building of the dialplan to include other features, such as +voicemail (\ref{voicemail}). + +However, note that there is a little bit of additional configuration needed if +the trunk is an IP channel. This is discussed in the section on trunks (\ref{trunks}). + +There are extensions for incoming calls on a specific trunk, which execute the SLATrunk +application, as well as incoming calls from a station, which execute SLAStation. +Note that there are multiple extensions for incoming calls from a station. This is +because the SLA system has to know whether the phone just went off hook, or if the +user pressed a specific line button. + +Also note that there is a hint for every line on every station. This lets the SLA +system control each individual light on every phone to ensure that it shows the +correct state of the line. The phones must subscribe to the state of each of their +line appearances. + +Please refer to the examples section for full dialplan samples for SLA. + +\subsection{Trunks} +\label{trunks} + +An SLA trunk is a mapping between a virtual trunk and a real Asterisk device. +This device may be an analog FXO line, or something like a SIP trunk. A trunk +must be configured in two places. First, configure the device itself in the +channel specific configuration file such as zapata.conf or sip.conf. Once the +trunk is configured, then map it to an SLA trunk in sla.conf. + +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +\end{verbatim} + +Be sure to configure the trunk's context to be the same one that is set for the +"autocontext" option in sla.conf if automatic dialplan configuration is used. +This would be done in the regular device entry in zapata.conf, sip.conf, etc. +Note that the automatic dialplan generation creates the SLATrunk() extension +at extension 's'. This is perfect for Zap channels that are FXO trunks, for +example. However, it may not be good enough for an IP trunk, since the call +coming in over the trunk may specify an actual number. + +If the dialplan is being built manually, ensure that calls coming in on a trunk +execute the SLATrunk() application with an argument of the trunk name, as shown +in the dialplan example before. + +IP trunks can be used, but they require some additional configuration to work. + +For this example, let's say we have a SIP trunk called "mytrunk" that is going +to be used as line4. Furthermore, when calls come in on this trunk, they are +going to say that they are calling the number "12564286000". Also, let's say +that the numbers that are valid for calling out this trunk are NANP numbers, +of the form \_1NXXNXXXXXX. + +In sip.conf, there would be an entry for [mytrunk]. For [mytrunk], +set context=line4. + + +\begin{verbatim} +[line4] +type=trunk +device=Local/disa@line4_outbound +\end{verbatim} + + +\begin{verbatim} +[line4] +exten => 12564286000,1,SLATrunk(line4) + +[line4_outbound] +exten => disa,1,Disa(no-password|line4_outbound) +exten => _1NXXNXXXXXX,1,Dial(SIP/\${EXTEN}@mytrunk) +\end{verbatim} + + +So, when a station picks up their phone and connects to line 4, they are +connected to the local dialplan. The Disa application plays dialtone to the +phone and collects digits until it matches an extension. In this case, once +the phone dials a number like 12565551212, the call will proceed out the +SIP trunk. + +\subsection{Stations} + +An SLA station is a mapping between a virtual station and a real Asterisk device. +Currently, the only channel driver that has all of the features necessary to +support an SLA environment is chan\_sip. So, to configure a SIP phone to use +as a station, you must configure sla.conf and sip.conf. + +\begin{verbatim} +[station1] +type=station +device=SIP/station1 +trunk=line1 +trunk=line2 +\end{verbatim} + +Here are some hints on configuring a SIP phone for use with SLA: + +\begin{enumerate} +\item Add the SIP channel as a [station] in sla.conf. + +\item Configure the phone in sip.conf. If automatic dialplan configuration was + used by enabling the "autocontext" option in sla.conf, then this entry in + sip.conf should have the same context setting. + +\item On the phone itself, there are various things that must be configured to + make everything work correctly: + + Let's say this phone is called "station1" in sla.conf, and it uses trunks + named "line1" and line2". + \begin{enumerate} + + \item Two line buttons must be configured to subscribe to the state of the + following extensions: + - station1\_line1 + - station1\_line2 + + \item The line appearance buttons should be configured to dial the extensions + that they are subscribed to when they are pressed. + + \item If you would like the phone to automatically connect to a trunk when it + is taken off hook, then the phone should be automatically configured to + dial "station1" when it is taken off hook. + + \end{enumerate} +\end{enumerate} + + +\section{Configuration Examples} +\subsection{Basic SLA} + +This is an example of the most basic SLA setup. It uses the automatic +dialplan generation so the configuration is minimal. + +sla.conf: +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +autocontext=line1 + +[line2] +type=trunk +device=Zap/2 +autocontext=line2 + +[station](!) +type=station +trunk=line1 +trunk=line2 +autocontext=sla_stations + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 + +\end{verbatim} + +With this configuration, the dialplan is generated automatically. The first +zap channel should have its context set to "line1" and the second should be +set to "line2" in zapata.conf. In sip.conf, station1, station2, and station3 +should all have their context set to "sla\_stations". + +For reference, here is the automatically generated dialplan for this situation: +\begin{verbatim} +[line1] +exten => s,1,SLATrunk(line1) + +[line2] +exten => s,2,SLATrunk(line2) + +[sla_stations] +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) +\end{verbatim} + + +\subsection{SLA and Voicemail} +\label{voicemail} + +This is an example of how you could set up a single voicemail box for the +phone system. The voicemail box number used in this example is 1234, which +would be configured in voicemail.conf. + +For this example, assume that there are 2 trunks and 3 stations. The trunks +are Zap/1 and Zap/2. The stations are SIP/station1, SIP/station2, and +SIP/station3. + +In zapata.conf, channel 1 has context=line1 and channel 2 has context=line2. + +In sip.conf, all three stations are configured with context=sla\_stations. + +When the stations pick up their phones to dial, they are allowed to dial +NANP numbers for outbound calls, or 8500 for checking voicemail. + + +sla.conf: +\begin{verbatim} +[line1] +type=trunk +device=Local/disa@line1_outbound + +[line2] +type=trunk +device=Local/disa@line2_outbound + +[station](!) +type=station +trunk=line1 +trunk=line2 + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 + +\end{verbatim} + + +extensions.conf: +\begin{verbatim} +[macro-slaline] +exten => s,1,SLATrunk(${ARG1}) +exten => s,n,Goto(s-${SLATRUNK_STATUS}|1) +exten => s-FAILURE,1,Voicemail(1234|u) +exten => s-UNANSWERED,1,Voicemail(1234|u) + +[line1] +exten => s,1,Macro(slaline|line1) + +[line2] +exten => s,2,Macro(slaline|line2) + +[line1_outbound] +exten => disa,1,Disa(no-password|line1_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[line2_outbound] +exten => disa,1,Disa(no-password|line2_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[sla_stations] + +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) + +\end{verbatim} + +\section{Call Handling} +\subsection{Summary} + +This section is intended to describe how Asterisk handles calls inside of the +SLA system so that it is clear what behavior is expected. + +\subsection{Station goes off hook (not ringing)} + +When a station goes off hook, it should initiate a call to Asterisk with the +extension that indicates that the phone went off hook without specifying a +specific line. In the examples in this document, for the station named +"station1", this extension is simply named, "station1". + +Asterisk will attempt to connect this station to the first available trunk +that is not in use. Asterisk will check the trunks in the order that they +were specified in the station entry in sla.conf. If all trunks are in use, +the call will be denied. + +If Asterisk is able to acquire an idle trunk for this station, then trunk +is connected to the station and the station will hear dialtone. The station +can then proceed to dial a number to call. As soon as a trunk is acquired, +all appearances of this line on stations will show that the line is in use. + +\subsection{Station goes off hook (ringing)} + +When a station goes off hook while it is ringing, it should simply answer +the call that had been initiated to it to make it ring. Once the station +has answered, Asterisk will figure out which trunk to connect it to. It +will connect it to the highest priority trunk that is currently ringing. +Trunk priority is determined by the order that the trunks are listed in +the station entry in sla.conf. + +\subsection{Line button on a station is pressed} + +When a line button is pressed on a station, the station should initiate a +call to Asterisk with the extension that indicates which line button was +pressed. In the examples given in this document, for a station named +"station1" and a trunk named "line1", the extension would be "station1\_line1". + +If the specified trunk is not in use, then the station will be connected to it and +will hear dialtone. All appearances of this trunk will then show that it +is now in use. + +If the specified trunk is on hold by this station, then this station will be +reconnected to the trunk. The line appearance for this trunk on this station +will now show in use. If this was the only station that had the call on hold, +then all appearances of this trunk will now show that it is in use. Otherwise, +all stations that are not currently connected to this trunk will show it +on hold. + +If the specified trunk is on hold by a different station, then this station +will be connected to the trunk only if the trunk itself and the station(s) that +have it on hold do not have private hold enabled. If connected, the appeareance +of this trunk on this station will then show in use. All stations that are not +currently connected to this trunk will show it on hold. + +%\end{document} |