func_math.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2004 - 2006, Andy Powell
 *
 * Updated by Mark Spencer <[email protected]>
 * Updated by Nir Simionovich <[email protected]>
 * Updated by Naveen Albert <[email protected]>
 *
 * 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 Math related dialplan function
 *
 * \author Andy Powell
 * \author Mark Spencer <[email protected]>
 * \author Nir Simionovich <[email protected]>
 * \author Naveen Albert <[email protected]>
 *
 * \ingroup functions
 */

/*** MODULEINFO
 <support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <math.h>

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

/*** DOCUMENTATION
 <function name="MATH" language="en_US">
 <synopsis>
 Performs Mathematical Functions.
 </synopsis>
 <syntax>
 <parameter name="expression" required="true">
 <para>Is of the form:
 <replaceable>number1</replaceable><replaceable>op</replaceable><replaceable>number2</replaceable>
 where the possible values for <replaceable>op</replaceable>
 are:</para>
 <para>+,-,/,*,%,&lt;&lt;,&gt;&gt;,^,AND,OR,XOR,&lt;,&gt;,&lt;=,&gt;=,== (and behave as their C equivalents)</para>
 </parameter>
 <parameter name="type">
 <para>Wanted type of result:</para>
 <para>f, float - float(default)</para>
 <para>i, int - integer</para>
 <para>h, hex - hex</para>
 <para>c, char - char</para>
 </parameter>
 </syntax>
 <description>
 <para>Performs mathematical functions based on two parameters and an operator. The returned
 value type is <replaceable>type</replaceable></para>
 <para>Example: Set(i=${MATH(123%16,int)}) - sets var i=11</para>
 </description>
 </function>
 <function name="INC" language="en_US">
 <synopsis>
 Increments the value of a variable, while returning the updated value to the dialplan
 </synopsis>
 <syntax>
 <parameter name="variable" required="true">
 <para>
 The variable name to be manipulated, without the braces.
 </para>
 </parameter>
 </syntax>
 <description>
 <para>Increments the value of a variable, while returning the updated value to the dialplan</para>
 <para>Example: INC(MyVAR) - Increments MyVar</para>
 <para>Note: INC(${MyVAR}) - Is wrong, as INC expects the variable name, not its value</para>
 </description>
 </function>
 <function name="DEC" language="en_US">
 <synopsis>
 Decrements the value of a variable, while returning the updated value to the dialplan
 </synopsis>
 <syntax>
 <parameter name="variable" required="true">
 <para>
 The variable name to be manipulated, without the braces.
 </para>
 </parameter>
 </syntax>
 <description>
 <para>Decrements the value of a variable, while returning the updated value to the dialplan</para>
 <para>Example: DEC(MyVAR) - Decrements MyVar</para>
 <para>Note: DEC(${MyVAR}) - Is wrong, as DEC expects the variable name, not its value</para>
 </description>
 </function>
 <function name="MIN" language="en_US">
 <synopsis>
 Returns the minimum of two numbers.
 </synopsis>
 <syntax>
 <parameter name="num1" />
 <parameter name="num2" />
 </syntax>
 <description>
 <para>Returns the minimum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
 <para>Example: Set(min=${MIN(7,4)});
 Sets the min variable equal to 4.</para>
 </description>
 </function>
 <function name="MAX" language="en_US">
 <synopsis>
 Returns the maximum of two numbers.
 </synopsis>
 <syntax>
 <parameter name="num1" />
 <parameter name="num2" />
 </syntax>
 <description>
 <para>Returns the maximum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
 <para>Example: Set(max=${MAX(4,7)});
 Sets the max variable equal to 7.</para>
 </description>
 </function>
 <function name="ABS" language="en_US">
 <synopsis>
 Returns absolute value of a number.
 </synopsis>
 <syntax>
 <parameter name="num" />
 </syntax>
 <description>
 <para>Returns the absolute value of a number <replaceable>num</replaceable>.</para>
 <para>Example: Set(absval=${ABS(-13)});
 Sets the absval variable equal to 13.</para>
 </description>
 </function>
 ***/

enum TypeOfFunctions {
 ADDFUNCTION,
 DIVIDEFUNCTION,
 MULTIPLYFUNCTION,
 SUBTRACTFUNCTION,
 MODULUSFUNCTION,
 POWFUNCTION,
 SHLEFTFUNCTION,
 SHRIGHTFUNCTION,
 BITWISEANDFUNCTION,
 BITWISEXORFUNCTION,
 BITWISEORFUNCTION,
 GTFUNCTION,
 LTFUNCTION,
 GTEFUNCTION,
 LTEFUNCTION,
 EQFUNCTION
};

enum TypeOfResult {
 FLOAT_RESULT,
 INT_RESULT,
 HEX_RESULT,
 CHAR_RESULT
};

static int math(struct ast_channel *chan, const char *cmd, char *parse,
 char *buf, size_t len)
{
 double fnum1;
 double fnum2;
 double ftmp = 0;
 char *op;
 int iaction = -1;
 int type_of_result = FLOAT_RESULT;
 char *mvalue1, *mvalue2 = NULL, *mtype_of_result;
 int negvalue1 = 0;
 AST_DECLARE_APP_ARGS(args,
 AST_APP_ARG(argv0);
 AST_APP_ARG(argv1);
 );

 if (ast_strlen_zero(parse)) {
 ast_log(LOG_WARNING, "Syntax: MATH(<number1><op><number 2>[,<type_of_result>]) - missing argument!\n");
 return -1;
 }

 AST_STANDARD_APP_ARGS(args, parse);

 if (args.argc < 1) {
 ast_log(LOG_WARNING, "Syntax: MATH(<number1><op><number 2>[,<type_of_result>]) - missing argument!\n");
 return -1;
 }

 mvalue1 = args.argv0;

 if (mvalue1[0] == '-') {
 negvalue1 = 1;
 mvalue1++;
 }

 if ((op = strchr(mvalue1, '*'))) {
 iaction = MULTIPLYFUNCTION;
 *op = '\0';
 } else if ((op = strchr(mvalue1, '/'))) {
 iaction = DIVIDEFUNCTION;
 *op = '\0';
 } else if ((op = strchr(mvalue1, '%'))) {
 iaction = MODULUSFUNCTION;
 *op = '\0';
 } else if ((op = strchr(mvalue1, '^'))) {
 iaction = POWFUNCTION;
 *op = '\0';
 } else if ((op = strstr(mvalue1, "AND"))) {
 iaction = BITWISEANDFUNCTION;
 *op = '\0';
 op += 2;
 } else if ((op = strstr(mvalue1, "XOR"))) {
 iaction = BITWISEXORFUNCTION;
 *op = '\0';
 op += 2;
 } else if ((op = strstr(mvalue1, "OR"))) {
 iaction = BITWISEORFUNCTION;
 *op = '\0';
 ++op;
 } else if ((op = strchr(mvalue1, '>'))) {
 iaction = GTFUNCTION;
 *op = '\0';
 if (*(op + 1) == '=') {
 iaction = GTEFUNCTION;
 ++op;
 } else if (*(op + 1) == '>') {
 iaction = SHRIGHTFUNCTION;
 ++op;
 }
 } else if ((op = strchr(mvalue1, '<'))) {
 iaction = LTFUNCTION;
 *op = '\0';
 if (*(op + 1) == '=') {
 iaction = LTEFUNCTION;
 ++op;
 } else if (*(op + 1) == '<') {
 iaction = SHLEFTFUNCTION;
 ++op;
 }
 } else if ((op = strchr(mvalue1, '='))) {
 *op = '\0';
 if (*(op + 1) == '=') {
 iaction = EQFUNCTION;
 ++op;
 } else
 op = NULL;
 } else if ((op = strchr(mvalue1, '+'))) {
 iaction = ADDFUNCTION;
 *op = '\0';
 } else if ((op = strchr(mvalue1, '-'))) { /* subtraction MUST always be last, in case we have a negative second number */
 iaction = SUBTRACTFUNCTION;
 *op = '\0';
 }

 if (op)
 mvalue2 = op + 1;

 /* detect wanted type of result */
 mtype_of_result = args.argv1;
 if (mtype_of_result) {
 if (!strcasecmp(mtype_of_result, "float")
 || !strcasecmp(mtype_of_result, "f"))
 type_of_result = FLOAT_RESULT;
 else if (!strcasecmp(mtype_of_result, "int")
 || !strcasecmp(mtype_of_result, "i"))
 type_of_result = INT_RESULT;
 else if (!strcasecmp(mtype_of_result, "hex")
 || !strcasecmp(mtype_of_result, "h"))
 type_of_result = HEX_RESULT;
 else if (!strcasecmp(mtype_of_result, "char")
 || !strcasecmp(mtype_of_result, "c"))
 type_of_result = CHAR_RESULT;
 else {
 ast_log(LOG_WARNING, "Unknown type of result requested '%s'.\n",
 mtype_of_result);
 return -1;
 }
 }

 if (!mvalue2) {
 ast_log(LOG_WARNING,
 "Supply all the parameters - just this once, please\n");
 return -1;
 }

 if (sscanf(mvalue1, "%30lf", &fnum1) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", mvalue1);
 return -1;
 }

 if (sscanf(mvalue2, "%30lf", &fnum2) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", mvalue2);
 return -1;
 }

 if (negvalue1)
 fnum1 = 0 - fnum1;

 switch (iaction) {
 case ADDFUNCTION:
 ftmp = fnum1 + fnum2;
 break;
 case DIVIDEFUNCTION:
 if (fnum2 <= 0)
 ftmp = 0; /* can't do a divide by 0 */
 else
 ftmp = (fnum1 / fnum2);
 break;
 case MULTIPLYFUNCTION:
 ftmp = (fnum1 * fnum2);
 break;
 case SUBTRACTFUNCTION:
 ftmp = (fnum1 - fnum2);
 break;
 case MODULUSFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;

 if (inum2 == 0) {
 ftmp = 0;
 } else {
 ftmp = (inum1 % inum2);
 }

 break;
 }
 case POWFUNCTION:
 ftmp = pow(fnum1, fnum2);
 break;
 case SHLEFTFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;

 ftmp = (inum1 << inum2);
 break;
 }
 case SHRIGHTFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;

 ftmp = (inum1 >> inum2);
 break;
 }
 case BITWISEANDFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;
 ftmp = (inum1 & inum2);
 break;
 }
 case BITWISEXORFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;
 ftmp = (inum1 ^ inum2);
 break;
 }
 case BITWISEORFUNCTION:
 {
 int inum1 = fnum1;
 int inum2 = fnum2;
 ftmp = (inum1 | inum2);
 break;
 }
 case GTFUNCTION:
 ast_copy_string(buf, (fnum1 > fnum2) ? "TRUE" : "FALSE", len);
 break;
 case LTFUNCTION:
 ast_copy_string(buf, (fnum1 < fnum2) ? "TRUE" : "FALSE", len);
 break;
 case GTEFUNCTION:
 ast_copy_string(buf, (fnum1 >= fnum2) ? "TRUE" : "FALSE", len);
 break;
 case LTEFUNCTION:
 ast_copy_string(buf, (fnum1 <= fnum2) ? "TRUE" : "FALSE", len);
 break;
 case EQFUNCTION:
 ast_copy_string(buf, (fnum1 == fnum2) ? "TRUE" : "FALSE", len);
 break;
 default:
 ast_log(LOG_WARNING,
 "Something happened that neither of us should be proud of %d\n",
 iaction);
 return -1;
 }

 if (iaction < GTFUNCTION || iaction > EQFUNCTION) {
 if (type_of_result == FLOAT_RESULT)
 snprintf(buf, len, "%f", ftmp);
 else if (type_of_result == INT_RESULT)
 snprintf(buf, len, "%i", (int) ftmp);
 else if (type_of_result == HEX_RESULT)
 snprintf(buf, len, "%x", (unsigned int) ftmp);
 else if (type_of_result == CHAR_RESULT)
 snprintf(buf, len, "%c", (unsigned char) ftmp);
 }

 return 0;
}

static int crement_function_read(struct ast_channel *chan, const char *cmd,
 char *data, char *buf, size_t len)
{
 int ret = -1;
 int int_value = 0;
 int modify_orig = 0;
 const char *var;
 char endchar = 0, returnvar[12]; /* If you need a variable longer than 11 digits - something is way wrong */

 if (ast_strlen_zero(data)) {
 ast_log(LOG_WARNING, "Syntax: %s(<data>) - missing argument!\n", cmd);
 return -1;
 }

 if (!chan) {
 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
 return -1;
 }

 ast_channel_lock(chan);

 if (!(var = pbx_builtin_getvar_helper(chan, data))) {
 ast_log(LOG_NOTICE, "Failed to obtain variable %s, bailing out\n", data);
 ast_channel_unlock(chan);
 return -1;
 }

 if (ast_strlen_zero(var)) {
 ast_log(LOG_NOTICE, "Variable %s doesn't exist - are you sure you wrote it correctly?\n", data);
 ast_channel_unlock(chan);
 return -1;
 }

 if (sscanf(var, "%30d%1c", &int_value, &endchar) == 0 || endchar != 0) {
 ast_log(LOG_NOTICE, "The content of ${%s} is not a numeric value - bailing out!\n", data);
 ast_channel_unlock(chan);
 return -1;
 }

 /* now we'll actually do something useful */
 if (!strcasecmp(cmd, "INC")) { /* Increment variable */
 int_value++;
 modify_orig = 1;
 } else if (!strcasecmp(cmd, "DEC")) { /* Decrement variable */
 int_value--;
 modify_orig = 1;
 }

 if (snprintf(returnvar, sizeof(returnvar), "%d", int_value) > 0) {
 pbx_builtin_setvar_helper(chan, data, returnvar);
 if (modify_orig) {
 ast_copy_string(buf, returnvar, len);
 }
 ret = 0;
 } else {
 pbx_builtin_setvar_helper(chan, data, "0");
 if (modify_orig) {
 ast_copy_string(buf, "0", len);
 }
 ast_log(LOG_NOTICE, "Variable %s refused to be %sREMENTED, setting value to 0", data, cmd);
 ret = 0;
 }

 ast_channel_unlock(chan);

 return ret;
}

static int acf_min_exec(struct ast_channel *chan, const char *cmd,
 char *parse, char *buffer, size_t buflen)
{
 double num1, num2, response_num = 0;
 AST_DECLARE_APP_ARGS(args,
 AST_APP_ARG(num1);
 AST_APP_ARG(num2);
 );

 AST_STANDARD_APP_ARGS(args, parse);

 if (ast_strlen_zero(args.num1) && ast_strlen_zero(args.num2)) {
 ast_log(LOG_ERROR, "Missing argument for number(s).");
 return -1;
 }

 if (ast_strlen_zero(args.num1)) {
 response_num = -1; /* couldn't read num1 successfully */
 } else if (sscanf(args.num1, "%30lf", &num1) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", args.num1);
 return -1;
 }

 if (ast_strlen_zero(args.num2)) {
 num2 = num1; /* num1 must be a valid integer here */
 } else if (sscanf(args.num2, "%30lf", &num2) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", args.num2);
 return -1;
 }

 if (response_num == -1) { /* could only read num2 */
 response_num = num2;
 } else {
 response_num = (num1 > num2) ? num2 : num1;
 }

 ast_debug(1, "%f is the minimum of [%f,%f]\n", response_num, num1, num2);
 if ((int) response_num == response_num) {
 snprintf(buffer, buflen, "%d", (int) response_num);
 } else {
 snprintf(buffer, buflen, "%f", response_num);
 }

 return 0;
}

static int acf_max_exec(struct ast_channel *chan, const char *cmd,
 char *parse, char *buffer, size_t buflen)
{
 double num1, num2, response_num = 0;
 AST_DECLARE_APP_ARGS(args,
 AST_APP_ARG(num1);
 AST_APP_ARG(num2);
 );

 AST_STANDARD_APP_ARGS(args, parse);

 if (ast_strlen_zero(args.num1) && ast_strlen_zero(args.num2)) {
 ast_log(LOG_ERROR, "Missing argument for number(s).");
 return -1;
 }

 if (ast_strlen_zero(args.num1)) {
 response_num = -1; /* couldn't read num1 successfully */
 } else if (sscanf(args.num1, "%30lf", &num1) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", args.num1);
 return -1;
 }

 if (ast_strlen_zero(args.num2)) {
 num2 = num1; /* num1 must be a valid integer here */
 } else if (sscanf(args.num2, "%30lf", &num2) != 1) {
 ast_log(LOG_WARNING, "'%s' is not a valid number\n", args.num2);
 return -1;
 }

 if (response_num == -1) { /* could only read num2 */
 response_num = num2;
 } else {
 response_num = (num1 < num2) ? num2 : num1;
 }

 ast_debug(1, "%f is the maximum of [%f,%f]\n", response_num, num1, num2);
 if ((int) response_num == response_num) {
 snprintf(buffer, buflen, "%d", (int) response_num);
 } else {
 snprintf(buffer, buflen, "%f", response_num);
 }

 return 0;
}

static int acf_abs_exec(struct ast_channel *chan, const char *cmd,
 char *parse, char *buffer, size_t buflen)
{
 double num1, response_num;
 AST_DECLARE_APP_ARGS(args,
 AST_APP_ARG(num1);
 );

 AST_STANDARD_APP_ARGS(args, parse);

 if (ast_strlen_zero(args.num1) || sscanf(args.num1, "%30lf", &num1) != 1) {
 ast_log(LOG_WARNING, "Bad or missing argument for number: %s", args.num1);
 return -1;
 }

 response_num = fabs(num1);
 ast_debug(1, "%f is the absolute value of %f\n", response_num, num1);
 if ((int) response_num == response_num) {
 snprintf(buffer, buflen, "%d", (int) response_num);
 } else {
 snprintf(buffer, buflen, "%f", response_num);
 }

 return 0;
}

static struct ast_custom_function math_function = {
 .name = "MATH",
 .read = math
};

static struct ast_custom_function increment_function = {
 .name = "INC",
 .read = crement_function_read,
};

static struct ast_custom_function decrement_function = {
 .name = "DEC",
 .read = crement_function_read,
};

static struct ast_custom_function acf_min = {
 .name = "MIN",
 .read = acf_min_exec,
 .read_max = 12,
};

static struct ast_custom_function acf_max = {
 .name = "MAX",
 .read = acf_max_exec,
 .read_max = 12,
};

static struct ast_custom_function acf_abs = {
 .name = "ABS",
 .read = acf_abs_exec,
 .read_max = 12,
};

#ifdef TEST_FRAMEWORK
AST_TEST_DEFINE(test_MATH_function)
{
 enum ast_test_result_state res = AST_TEST_PASS;
 struct ast_str *expr, *result;

 switch (cmd) {
 case TEST_INIT:
 info->name = "test_MATH_function";
 info->category = "/main/pbx/";
 info->summary = "Test MATH function substitution";
 info->description =
 "Executes a series of variable substitutions using the MATH function and ensures that the expected results are received.";
 return AST_TEST_NOT_RUN;
 case TEST_EXECUTE:
 break;
 }

 ast_test_status_update(test, "Testing MATH() substitution ...\n");

 if (!(expr = ast_str_create(16))) {
 return AST_TEST_FAIL;
 }
 if (!(result = ast_str_create(16))) {
 ast_free(expr);
 return AST_TEST_FAIL;
 }

 ast_str_set(&expr, 0, "${MATH(170 AND 63,i)}");
 ast_str_substitute_variables(&result, 0, NULL, ast_str_buffer(expr));
 if (strcmp(ast_str_buffer(result), "42") != 0) {
 ast_test_status_update(test, "Expected result '42' not returned! ('%s')\n",
 ast_str_buffer(result));
 res = AST_TEST_FAIL;
 }

 ast_str_set(&expr, 0, "${MATH(170AND63,i)}");
 ast_str_substitute_variables(&result, 0, NULL, ast_str_buffer(expr));
 if (strcmp(ast_str_buffer(result), "42") != 0) {
 ast_test_status_update(test, "Expected result '42' not returned! ('%s')\n",
 ast_str_buffer(result));
 res = AST_TEST_FAIL;
 }

 ast_free(expr);
 ast_free(result);

 return res;
}
#endif

static int unload_module(void)
{
 int res = 0;

 res |= ast_custom_function_unregister(&math_function);
 res |= ast_custom_function_unregister(&increment_function);
 res |= ast_custom_function_unregister(&decrement_function);
 res |= ast_custom_function_unregister(&acf_min);
 res |= ast_custom_function_unregister(&acf_max);
 res |= ast_custom_function_unregister(&acf_abs);
 AST_TEST_UNREGISTER(test_MATH_function);

 return res;
}

static int load_module(void)
{
 int res = 0;

 res |= ast_custom_function_register(&math_function);
 res |= ast_custom_function_register(&increment_function);
 res |= ast_custom_function_register(&decrement_function);
 res |= ast_custom_function_register(&acf_min);
 res |= ast_custom_function_register(&acf_max);
 res |= ast_custom_function_register(&acf_abs);
 AST_TEST_REGISTER(test_MATH_function);

 return res;
}

AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Mathematical dialplan function");