func_evalexten.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2021, Naveen Albert
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief Dialplan extension evaluation function
 *
 * \author Naveen Albert <[email protected]>
 *
 * \ingroup functions
 */

/*** MODULEINFO
   <support_level>extended</support_level>
 ***/

#include "asterisk.h"

#include "asterisk/module.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/utils.h"
#include "asterisk/app.h"

/*** DOCUMENTATION
   <function name="EVAL_EXTEN" language="en_US">
      <synopsis>
         Evaluates the contents of a dialplan extension and returns it as a string.
      </synopsis>
      <syntax>
         <parameter name="context" />
         <parameter name="extensions" />
         <parameter name="priority" required="true" />
      </syntax>
      <description>
         <para>The EVAL_EXTEN function looks up a dialplan entry by context,extension,priority,
         evaluates the contents of a Return statement to resolve any variable or function
         references, and returns the result as a string.</para>
         <para>You can use this function to create simple user-defined lookup tables or
         user-defined functions.</para>
         <example title="Custom dialplan functions">
         [call-types]
         exten => _1NNN,1,Return(internal)
         exten => _NXXNXXXXXX,1,Return(external)

         [udf]
         exten => calleridlen,1,Return(${LEN(${CALLERID(num)})})

         [default]
         exten => _X!,1,Verbose(Call type ${EVAL_EXTEN(call-types,${EXTEN},1)} - ${EVAL_EXTEN(udf,calleridlen,1)})
         </example>
         <para>Any variables in the evaluated data will be resolved in the context of
         that extension. For example, <literal>${EXTEN}</literal> would refer to the
         EVAL_EXTEN extension, not the extension in the context invoking the function.
         This behavior is similar to other applications, e.g. <literal>Gosub</literal>.</para>
         <example title="Choosing which prompt to use">
         same => n,Read(input,${EVAL_EXTEN(prompts,${CALLERID(num)},1)})
         
         [prompts]
         exten => _X!,1,Return(default)
         exten => _20X,1,Return(welcome)
         exten => _2XX,1,Return(${DB(promptsettings/${EXTEN})})
         </example>
         <para>Extensions on which EVAL_EXTEN is invoked are not different from other
         extensions. However, the application at that extension is not executed.
         Only the application data is parsed and evaluated.</para>
         <para>A limitation of this function is that the application at the specified
         extension isn't actually executed, and thus unlike a Gosub, you can't pass
         arguments in the EVAL_EXTEN function.</para>
      </description>
      <see-also>
         <ref type="function">EVAL</ref>
      </see-also>
   </function>
 ***/

static int get_extension_data(char *name, int namesize, struct ast_channel *c,
   const char *context, const char *exten, int priority)
{
   struct ast_exten *e;
   struct pbx_find_info q = { .stacklen = 0 }; /* the rest is set in pbx_find_context */
   ast_rdlock_contexts();
   e = pbx_find_extension(c, NULL, &q, context, exten, priority, NULL, "", E_MATCH);
   ast_unlock_contexts();
   if (e) {
      if (name) {
         const char *tmp = ast_get_extension_app_data(e);
         if (tmp) {
            ast_copy_string(name, tmp, namesize);
         }
      }
      return 0;
   }
   return -1;
}

static int eval_exten_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
{
   char *exten, *pri, *context, *parse;
   int ipri;
   const char *realcontext, *realexten;
   int realpriority;
   char tmpbuf[len];

   if (ast_strlen_zero(data)) {
      ast_log(LOG_WARNING, "The EVAL_EXTEN function requires an extension\n");
      return -1;
   }

   parse = ast_strdupa(data);
   /* Split context,exten,pri */
   context = strsep(&parse, ",");
   exten = strsep(&parse, ",");
   pri = strsep(&parse, ",");
   if (!exten) {
      /* Only a priority in this one */
      pri = context;
      exten = NULL;
      context = NULL;
   } else if (!pri) {
      /* Only an extension and priority in this one */
      pri = exten;
      exten = context;
      context = NULL;
   }
   ast_debug(1, "Context, extension, priority: %s, %s, %s\n", context, exten, pri);
   if (sscanf(pri, "%30d", &ipri) != 1) {
      ipri = ast_findlabel_extension(chan, context ? context : ast_channel_context(chan),
         exten ? exten : ast_channel_exten(chan), pri,
         S_COR(ast_channel_caller(chan)->id.number.valid, ast_channel_caller(chan)->id.number.str, NULL));
      if (ipri < 1) {
         ast_log(LOG_WARNING, "Priority '%s' must be a number > 0, or valid label\n", pri);
         return -1;
      }
   }
   ast_debug(1, "Context, extension, priority: %s, %s, %d\n", context, exten, ipri);

   ast_channel_lock(chan);
   realcontext = ast_strdupa(ast_channel_context(chan));
   realexten = ast_strdupa(ast_channel_exten(chan));
   realpriority = ast_channel_priority(chan);
   ast_channel_unlock(chan);
   if (ast_strlen_zero(exten)) {
      exten = ast_strdupa(realexten);
   }
   if (ast_strlen_zero(context)) {
      context = ast_strdupa(realcontext);
   }

   if (get_extension_data(tmpbuf, len, chan, context, exten, ipri)) {
      return -1; /* EVAL_EXTEN failed */
   }
   /* Substitute variables now, using the location of the evaluated extension */
   /* strdupa required or we'll just overwrite what we read when we set these */
   ast_channel_lock(chan);
   ast_channel_context_set(chan, context);
   ast_channel_exten_set(chan, exten);
   ast_channel_priority_set(chan, ipri);
   ast_channel_unlock(chan);

   pbx_substitute_variables_helper(chan, tmpbuf, buf, len);

   ast_channel_lock(chan);
   ast_channel_context_set(chan, realcontext);
   ast_channel_exten_set(chan, realexten);
   ast_channel_priority_set(chan, realpriority);
   ast_channel_unlock(chan);

   return 0;
}

static struct ast_custom_function eval_exten_function = {
   .name = "EVAL_EXTEN",
   .read = eval_exten_read,
};

static int unload_module(void)
{
   return ast_custom_function_unregister(&eval_exten_function);
}

static int load_module(void)
{
   return ast_custom_function_register(&eval_exten_function);
}

AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Extension evaluation function");