Mon Aug 31 12:30:08 2015

Asterisk developer's documentation


func_db.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2005-2006, Russell Bryant <russelb@clemson.edu> 
00005  *
00006  * func_db.c adapted from the old app_db.c, copyright by the following people 
00007  * Copyright (C) 2005, Mark Spencer <markster@digium.com>
00008  * Copyright (C) 2003, Jefferson Noxon <jeff@debian.org>
00009  *
00010  * See http://www.asterisk.org for more information about
00011  * the Asterisk project. Please do not directly contact
00012  * any of the maintainers of this project for assistance;
00013  * the project provides a web site, mailing lists and IRC
00014  * channels for your use.
00015  *
00016  * This program is free software, distributed under the terms of
00017  * the GNU General Public License Version 2. See the LICENSE file
00018  * at the top of the source tree.
00019  */
00020 
00021 /*! \file
00022  *
00023  * \brief Functions for interaction with the Asterisk database
00024  *
00025  * \author Russell Bryant <russelb@clemson.edu>
00026  *
00027  * \ingroup functions
00028  */
00029 
00030 /*** MODULEINFO
00031    <support_level>core</support_level>
00032  ***/
00033 
00034 #include "asterisk.h"
00035 
00036 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 428431 $")
00037 
00038 #include <regex.h>
00039 
00040 #include "asterisk/module.h"
00041 #include "asterisk/channel.h"
00042 #include "asterisk/pbx.h"
00043 #include "asterisk/utils.h"
00044 #include "asterisk/app.h"
00045 #include "asterisk/astdb.h"
00046 
00047 /*** DOCUMENTATION
00048    <function name="DB" language="en_US">
00049       <synopsis>
00050          Read from or write to the Asterisk database.
00051       </synopsis>
00052       <syntax argsep="/">
00053          <parameter name="family" required="true" />
00054          <parameter name="key" required="true" />
00055       </syntax>
00056       <description>
00057          <para>This function will read from or write a value to the Asterisk database.  On a
00058          read, this function returns the corresponding value from the database, or blank
00059          if it does not exist.  Reading a database value will also set the variable
00060          DB_RESULT.  If you wish to find out if an entry exists, use the DB_EXISTS
00061          function.</para>
00062       </description>
00063       <see-also>
00064          <ref type="application">DBdel</ref>
00065          <ref type="function">DB_DELETE</ref>
00066          <ref type="application">DBdeltree</ref>
00067          <ref type="function">DB_EXISTS</ref>
00068       </see-also>
00069    </function>
00070    <function name="DB_EXISTS" language="en_US">
00071       <synopsis>
00072          Check to see if a key exists in the Asterisk database.
00073       </synopsis>
00074       <syntax argsep="/">
00075          <parameter name="family" required="true" />
00076          <parameter name="key" required="true" />
00077       </syntax>
00078       <description>
00079          <para>This function will check to see if a key exists in the Asterisk
00080          database. If it exists, the function will return <literal>1</literal>. If not,
00081          it will return <literal>0</literal>.  Checking for existence of a database key will
00082          also set the variable DB_RESULT to the key's value if it exists.</para>
00083       </description>
00084       <see-also>
00085          <ref type="function">DB</ref>
00086       </see-also>
00087    </function>
00088    <function name="DB_DELETE" language="en_US">
00089       <synopsis>
00090          Return a value from the database and delete it.
00091       </synopsis>
00092       <syntax argsep="/">
00093          <parameter name="family" required="true" />
00094          <parameter name="key" required="true" />
00095       </syntax>
00096       <description>
00097          <para>This function will retrieve a value from the Asterisk database
00098          and then remove that key from the database. <variable>DB_RESULT</variable>
00099          will be set to the key's value if it exists.</para>
00100          <note>
00101             <para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
00102             is set to <literal>no</literal>, this function can only be read from the
00103             dialplan, and not directly from external protocols. It can, however, be
00104             executed as a write operation (<literal>DB_DELETE(family, key)=ignored</literal>)</para>
00105          </note>
00106       </description>
00107       <see-also>
00108          <ref type="application">DBdel</ref>
00109          <ref type="function">DB</ref>
00110          <ref type="application">DBdeltree</ref>
00111       </see-also>
00112    </function>
00113  ***/
00114 
00115 static int function_db_read(struct ast_channel *chan, const char *cmd,
00116              char *parse, char *buf, size_t len)
00117 {
00118    AST_DECLARE_APP_ARGS(args,
00119       AST_APP_ARG(family);
00120       AST_APP_ARG(key);
00121    );
00122 
00123    buf[0] = '\0';
00124 
00125    if (ast_strlen_zero(parse)) {
00126       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
00127       return -1;
00128    }
00129 
00130    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00131 
00132    if (args.argc < 2) {
00133       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
00134       return -1;
00135    }
00136 
00137    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00138       ast_debug(1, "DB: %s/%s not found in database.\n", args.family, args.key);
00139    } else {
00140       pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00141    }
00142 
00143    return 0;
00144 }
00145 
00146 static int function_db_write(struct ast_channel *chan, const char *cmd, char *parse,
00147               const char *value)
00148 {
00149    AST_DECLARE_APP_ARGS(args,
00150       AST_APP_ARG(family);
00151       AST_APP_ARG(key);
00152    );
00153 
00154    if (ast_strlen_zero(parse)) {
00155       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=<value>\n");
00156       return -1;
00157    }
00158 
00159    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00160 
00161    if (args.argc < 2) {
00162       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=value\n");
00163       return -1;
00164    }
00165 
00166    if (ast_db_put(args.family, args.key, value)) {
00167       ast_log(LOG_WARNING, "DB: Error writing value to database.\n");
00168    }
00169 
00170    return 0;
00171 }
00172 
00173 static struct ast_custom_function db_function = {
00174    .name = "DB",
00175    .read = function_db_read,
00176    .write = function_db_write,
00177 };
00178 
00179 static int function_db_exists(struct ast_channel *chan, const char *cmd,
00180                char *parse, char *buf, size_t len)
00181 {
00182    AST_DECLARE_APP_ARGS(args,
00183       AST_APP_ARG(family);
00184       AST_APP_ARG(key);
00185    );
00186 
00187    buf[0] = '\0';
00188 
00189    if (ast_strlen_zero(parse)) {
00190       ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
00191       return -1;
00192    }
00193 
00194    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00195 
00196    if (args.argc < 2) {
00197       ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
00198       return -1;
00199    }
00200 
00201    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00202       strcpy(buf, "0");
00203    } else {
00204       pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00205       strcpy(buf, "1");
00206    }
00207 
00208    return 0;
00209 }
00210 
00211 static struct ast_custom_function db_exists_function = {
00212    .name = "DB_EXISTS",
00213    .read = function_db_exists,
00214    .read_max = 2,
00215 };
00216 
00217 static int function_db_delete(struct ast_channel *chan, const char *cmd,
00218                char *parse, char *buf, size_t len)
00219 {
00220    AST_DECLARE_APP_ARGS(args,
00221       AST_APP_ARG(family);
00222       AST_APP_ARG(key);
00223    );
00224 
00225    buf[0] = '\0';
00226 
00227    if (ast_strlen_zero(parse)) {
00228       ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
00229       return -1;
00230    }
00231 
00232    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00233 
00234    if (args.argc < 2) {
00235       ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
00236       return -1;
00237    }
00238 
00239    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00240       ast_debug(1, "DB_DELETE: %s/%s not found in database.\n", args.family, args.key);
00241    } else {
00242       if (ast_db_del(args.family, args.key)) {
00243          ast_debug(1, "DB_DELETE: %s/%s could not be deleted from the database\n", args.family, args.key);
00244       }
00245    }
00246 
00247    pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00248 
00249    return 0;
00250 }
00251 
00252 /*!
00253  * \brief Wrapper to execute DB_DELETE from a write operation. Allows execution
00254  * even if live_dangerously is disabled.
00255  */
00256 static int function_db_delete_write(struct ast_channel *chan, const char *cmd, char *parse,
00257    const char *value)
00258 {
00259    /* Throwaway to hold the result from the read */
00260    char buf[128];
00261    return function_db_delete(chan, cmd, parse, buf, sizeof(buf));
00262 }
00263 
00264 static struct ast_custom_function db_delete_function = {
00265    .name = "DB_DELETE",
00266    .read = function_db_delete,
00267    .write = function_db_delete_write,
00268 };
00269 
00270 static int unload_module(void)
00271 {
00272    int res = 0;
00273 
00274    res |= ast_custom_function_unregister(&db_function);
00275    res |= ast_custom_function_unregister(&db_exists_function);
00276    res |= ast_custom_function_unregister(&db_delete_function);
00277 
00278    return res;
00279 }
00280 
00281 static int load_module(void)
00282 {
00283    int res = 0;
00284 
00285    res |= ast_custom_function_register_escalating(&db_function, AST_CFE_BOTH);
00286    res |= ast_custom_function_register(&db_exists_function);
00287    res |= ast_custom_function_register_escalating(&db_delete_function, AST_CFE_READ);
00288 
00289    return res;
00290 }
00291 
00292 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Database (astdb) related dialplan functions");

Generated on 31 Aug 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1