kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-04 03:50:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Macro(), MacroExit(), MacroExclusive() and

Browse Source 
MacroIf() applications XML documentation.

(closes issue #13699)
Reported by: snuffy
Patches:
      bug13699_20081016.diff uploaded by snuffy (license 35)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@154796 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Eliel C. Sardanons
2008-11-05 18:46:29 +00:00
parent 5f1bcb136f
commit 45e6c880cd
1 changed files with 112 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
apps/app_macro.c
View File

@@ -37,67 +37,124 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
#include "asterisk/utils.h"
#include "asterisk/lock.h"
/*** DOCUMENTATION
<application name="Macro" language="en_US">
<synopsis>
Macro Implementation.
</synopsis>
<syntax>
<parameter name="name" required="true">
<para>The name of the macro</para>
</parameter>
<parameter name="args">
<argument name="arg1" required="true" />
<argument name="arg2" multiple="true" />
</parameter>
</syntax>
<description>
<para>Executes a macro using the context macro-<replaceable>name</replaceable>,
jumping to the <literal>s</literal> extension of that context and executing each step,
then returning when the steps end.</para>
<para>The calling extension, context, and priority are stored in <variable>MACRO_EXTEN</variable>,
<variable>MACRO_CONTEXT</variable> and <variable>MACRO_PRIORITY</variable> respectively. Arguments
become <variable>ARG1</variable>, <variable>ARG2</variable>, etc in the macro context.</para>
<para>If you Goto out of the Macro context, the Macro will terminate and control will be returned
at the location of the Goto.</para>
<para>If <variable>MACRO_OFFSET</variable> is set at termination, Macro will attempt to continue
at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.</para>
<para>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 <literal>h</literal> 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)</para>
<warning><para>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.</para></warning>
</description>
<see-also>
<ref type="application">MacroExit</ref>
<ref type="application">Goto</ref>
<ref type="application">Gosub</ref>
</see-also>
</application>
<application name="MacroIf" language="en_US">
<synopsis>
Conditional Macro implementation.
</synopsis>
<syntax argsep="?">
<parameter name="expr" required="true" />
<parameter name="destination" required="true" argsep=":">
<argument name="macroiftrue" required="true">
<argument name="macroiftrue" required="true" />
<argument name="arg1" multiple="true" />
</argument>
<argument name="macroiffalse">
<argument name="macroiffalse" required="true" />
<argument name="arg1" multiple="true" />
</argument>
</parameter>
</syntax>
<description>
<para>Executes macro defined in <replaceable>macroiftrue</replaceable> if
<replaceable>expr</replaceable> is true (otherwise <replaceable>macroiffalse</replaceable>
if provided)</para>
<para>Arguments and return values as in application Macro()</para>
</description>
<see-also>
<ref type="application">GotoIf</ref>
<ref type="application">GosubIf</ref>
<ref type="function">IF</ref>
</see-also>
</application>
<application name="MacroExclusive" language="en_US">
<synopsis>
Exclusive Macro Implementation.
</synopsis>
<syntax>
<parameter name="name" required="true">
<para>The name of the macro</para>
</parameter>
<parameter name="arg1" />
<parameter name="arg2" multiple="true" />
</syntax>
<description>
<para>Executes macro defined in the context macro-<replaceable>name</replaceable>.
Only one call at a time may run the macro. (we'll wait if another call is busy
executing in the Macro)</para>
<para>Arguments and return values as in application Macro()</para>
</description>
<see-also>
<ref type="application">Macro</ref>
</see-also>
</application>
<application name="MacroExit" language="en_US">
<synopsis>
Exit from Macro.
</synopsis>
<syntax />
<description>
<para>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.</para>
</description>
<see-also>
<ref type="application">Macro</ref>
</see-also>
</application>
***/
#define MAX_ARGS 80
/* special result value used to force macro exit */
#define MACRO_EXIT_RESULT 1024
static char *descrip =
" Macro(macroname,arg1,arg2...): Executes a macro using the context\n"
"'macro-<macroname>', jumping to the 's' extension of that context and\n"
"executing each step, then returning when the steps end. \n"
"The calling extension, context, and priority are stored in ${MACRO_EXTEN}, \n"
"${MACRO_CONTEXT} and ${MACRO_PRIORITY} respectively. Arguments become\n"
"${ARG1}, ${ARG2}, etc in the macro context.\n"
"If you Goto out of the Macro context, the Macro will terminate and control\n"
"will be returned at the location of the Goto.\n"
"If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue\n"
"at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.\n"
"Extensions: While a macro is being executed, it becomes the current context.\n"
" This means that if a hangup occurs, for instance, that the macro\n"
" will be searched for an 'h' extension, NOT the context from which\n"
" the macro was called. So, make sure to define all appropriate\n"
" extensions in your macro! (Note: AEL does not use macros)\n"
"WARNING: Because of the way Macro is implemented (it executes the priorities\n"
" contained within it via sub-engine), and a fixed per-thread\n"
" memory stack allowance, macros are limited to 7 levels\n"
" of nesting (macro calling macro calling macro, etc.); It\n"
" may be possible that stack-intensive applications in deeply nested macros\n"
" could cause asterisk to crash earlier than this limit. It is advised that\n"
" if you need to deeply nest macro calls, that you use the Gosub application\n"
" (now allows arguments like a Macro) with explict Return() calls instead.\n";
static char *if_descrip =
" MacroIf(<expr>?macroname_a[,arg1][:macroname_b[,arg1]])\n"
"Executes macro defined in <macroname_a> if <expr> is true\n"
"(otherwise <macroname_b> if provided)\n"
"Arguments and return values as in application Macro()\n";
static char *exclusive_descrip =
" MacroExclusive(macroname,arg1,arg2...):\n"
"Executes macro defined in the context 'macro-macroname'\n"
"Only one call at a time may run the macro.\n"
"(we'll wait if another call is busy executing in the Macro)\n"
"Arguments and return values as in application Macro()\n";
static char *exit_descrip =
" MacroExit():\n"
"Causes the currently running macro to exit as if it had\n"
"ended normally by running out of priorities to execute.\n"
"If used outside a macro, will likely cause unexpected\n"
"behavior.\n";
static char *app = "Macro";
static char *if_app = "MacroIf";
static char *exclusive_app = "MacroExclusive";
static char *exit_app = "MacroExit";
static char *synopsis = "Macro Implementation";
static char *if_synopsis = "Conditional Macro Implementation";
static char *exclusive_synopsis = "Exclusive Macro Implementation";
static char *exit_synopsis = "Exit From Macro";
static struct ast_exten *find_matching_priority(struct ast_context *c, const char *exten, int priority, const char *callerid)
{
struct ast_exten *e;
@@ -524,10 +581,10 @@ static int load_module(void)
{
int res;
res = ast_register_application(exit_app, macro_exit_exec, exit_synopsis, exit_descrip);
res |= ast_register_application(if_app, macroif_exec, if_synopsis, if_descrip);
res |= ast_register_application(exclusive_app, macroexclusive_exec, exclusive_synopsis, exclusive_descrip);
res |= ast_register_application(app, macro_exec, synopsis, descrip);
res = ast_register_application_xml(exit_app, macro_exit_exec);
res |= ast_register_application_xml(if_app, macroif_exec);
res |= ast_register_application_xml(exclusive_app, macroexclusive_exec);
res |= ast_register_application_xml(app, macro_exec);
return res;
}