From 07166788fd2b0203a4680be582129b3c8fbc9da8 Mon Sep 17 00:00:00 2001 From: Naveen Albert Date: Thu, 17 Oct 2024 09:18:45 -0400 Subject: [PATCH] func_evalexten: Add EVAL_SUB function. This adds an EVAL_SUB function, which is similar to the existing EVAL_EXTEN function but significantly more powerful, as it allows executing arbitrary dialplan and capturing its return value as the function's output. While EVAL_EXTEN should be preferred if it is possible to use it, EVAL_SUB can be used in a wider variety of cases and allows arbitrary computation to be performed in a dialplan function call, leveraging the dialplan. Resolves: #951 (cherry picked from commit 34662cf0ea5fd3ff8d6d95ba0a20770e7ed94452) --- funcs/func_evalexten.c | 99 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 96 insertions(+), 3 deletions(-) diff --git a/funcs/func_evalexten.c b/funcs/func_evalexten.c index 6a7d28bc90..df7d96411d 100644 --- a/funcs/func_evalexten.c +++ b/funcs/func_evalexten.c @@ -1,7 +1,7 @@ /* * Asterisk -- An open source telephony toolkit. * - * Copyright (C) 2021, Naveen Albert + * Copyright (C) 2021, 2024, Naveen Albert * * See http://www.asterisk.org for more information about * the Asterisk project. Please do not directly contact @@ -81,9 +81,64 @@ 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. + If you need the ability to evaluate more complex logic that cannot be done + purely using functions, see EVAL_SUB. EVAL + EVAL_SUB + + + + + Executes a Gosub and provides its return value as a string + + + + + + + + The EVAL_SUB function executes up a dialplan location by context,extension,priority, with optional arguments + and returns the contents of the Return statement. The arguments to EVAL_SUB + are exactly like they are with Gosub. + This function is complementary to EVAL_EXTEN. However, it is more powerful, + since it allows executing arbitrary dialplan and capturing some outcome as a dialplan function's + return value, allowing it to be used in a variety of scenarios that do not allow executing dialplan + directly but allow variables and functions to be used, and where using EVAL_EXTEN + would be difficult or impossible. + Consequently, this function also allows you to implement your own arbitrary functions + in dialplan, which can then be wrapped using the Asterisk function interface using EVAL_SUB. + While this function is primarily intended to be used for executing Gosub routines that are quick + and do not interact with the channel, it is safe to execute arbitrary, even blocking, dialplan in the + called subroutine. That said, this kind of usage is not recommended. + This function will always return, even if the channel is hung up. + + [islocal] + exten => _X!,1,ExecIf($[${LEN(${EXTEN})}<10]?Return(1)) + same => n,Set(LOCAL(npanxx)=${EXTEN:-10:6}) + same => n,ReturnIf(${EXISTS(${DB(localcall/${npanxx})})}?${DB(localcall/${npanxx})}) + same => n,Set(LOCAL(islocal)=${SHELL(curl "https://example.com/islocal?npanxx=${EXTEN:-10:6}")}) + same => n,Set(LOCAL(islocal)=${FILTER(A-Z,${islocal})}) + same => n,Set(DB(localcall/${npanxx})=${islocal}) + same => n,Return(${islocal}) + + [outgoing] + exten => _1NXXNXXXXXX,1,Set(CDR(toll)=${IF($["${EVAL_SUB(islocal,${EXTEN},1)}"="Y"]?0:1)}) + same => n,Dial(DAHDI/1/${EXTEN}) + same => n,Hangup() + + This example illustrates an example of logic that would be difficult to capture + in a way that a single call to EVAL_EXTEN would return the same result. For one, conditionals + are involved, and due to the way Asterisk parses dialplan, all functions in an application call are evaluated all the + time, which may be undesirable if they cause side effects (e.g. making a cURL request) that should only happen in certain circumstances. + The above example, of course, does not require the use of this function, as it could have been invoked + using the Gosub application directly. However, if constrained to just using variables or functions, + EVAL_SUB would be required. + + + EVAL_EXTEN + Return ***/ @@ -129,19 +184,57 @@ static int eval_exten_read(struct ast_channel *chan, const char *cmd, char *data return 0; } +static int eval_sub_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) +{ + int gosub_res; + const char *retval; + + if (ast_strlen_zero(data)) { + ast_log(LOG_WARNING, "The EVAL_SUB function requires an extension\n"); + *buf = '\0'; + return -1; + } + + /* Ignore hangups since we want to retrieve a value, and this function could be called at hangup time */ + gosub_res = ast_app_exec_sub(NULL, chan, data, 1); + if (gosub_res) { + ast_log(LOG_WARNING, "Failed to execute Gosub(%s)\n", data); + *buf = '\0'; + return -1; + } + + ast_channel_lock(chan); + retval = pbx_builtin_getvar_helper(chan, "GOSUB_RETVAL"); + ast_copy_string(buf, S_OR(retval, ""), len); /* Overwrite, even if empty, to ensure a stale GOSUB_RETVAL isn't returned as our value */ + ast_channel_unlock(chan); + + return 0; +} + static struct ast_custom_function eval_exten_function = { .name = "EVAL_EXTEN", .read = eval_exten_read, }; +static struct ast_custom_function eval_sub_function = { + .name = "EVAL_SUB", + .read = eval_sub_read, +}; + static int unload_module(void) { - return ast_custom_function_unregister(&eval_exten_function); + int res = 0; + res |= ast_custom_function_unregister(&eval_exten_function); + res |= ast_custom_function_unregister(&eval_sub_function); + return res; } static int load_module(void) { - return ast_custom_function_register(&eval_exten_function); + int res = 0; + res |= ast_custom_function_register(&eval_exten_function); + res |= ast_custom_function_register(&eval_sub_function); + return res; } AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Extension evaluation function");