Thu Apr 28 2011 17:13:33

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 #include "asterisk.h"
00031 
00032 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 154542 $")
00033 
00034 #include <regex.h>
00035 
00036 #include "asterisk/module.h"
00037 #include "asterisk/channel.h"
00038 #include "asterisk/pbx.h"
00039 #include "asterisk/utils.h"
00040 #include "asterisk/app.h"
00041 #include "asterisk/astdb.h"
00042 
00043 /*** DOCUMENTATION
00044    <function name="DB" language="en_US">
00045       <synopsis>
00046          Read from or write to the Asterisk database.
00047       </synopsis>
00048       <syntax argsep="/">
00049          <parameter name="family" required="true" />
00050          <parameter name="key" required="true" />
00051       </syntax>
00052       <description>
00053          <para>This function will read from or write a value to the Asterisk database.  On a
00054          read, this function returns the corresponding value from the database, or blank
00055          if it does not exist.  Reading a database value will also set the variable
00056          DB_RESULT.  If you wish to find out if an entry exists, use the DB_EXISTS
00057          function.</para>
00058       </description>
00059       <see-also>
00060          <ref type="application">DBdel</ref>
00061          <ref type="function">DB_DELETE</ref>
00062          <ref type="application">DBdeltree</ref>
00063          <ref type="function">DB_EXISTS</ref>
00064       </see-also>
00065    </function>
00066    <function name="DB_EXISTS" language="en_US">
00067       <synopsis>
00068          Check to see if a key exists in the Asterisk database.
00069       </synopsis>
00070       <syntax argsep="/">
00071          <parameter name="family" required="true" />
00072          <parameter name="key" required="true" />
00073       </syntax>
00074       <description>
00075          <para>This function will check to see if a key exists in the Asterisk
00076          database. If it exists, the function will return <literal>1</literal>. If not,
00077          it will return <literal>0</literal>.  Checking for existence of a database key will
00078          also set the variable DB_RESULT to the key's value if it exists.</para>
00079       </description>
00080       <see-also>
00081          <ref type="function">DB</ref>
00082       </see-also>
00083    </function>
00084    <function name="DB_DELETE" language="en_US">
00085       <synopsis>
00086          Return a value from the database and delete it.
00087       </synopsis>
00088       <syntax argsep="/">
00089          <parameter name="family" required="true" />
00090          <parameter name="key" required="true" />
00091       </syntax>
00092       <description>
00093          <para>This function will retrieve a value from the Asterisk database
00094          and then remove that key from the database. <variable>DB_RESULT</variable>
00095          will be set to the key's value if it exists.</para>
00096       </description>
00097       <see-also>
00098          <ref type="application">DBdel</ref>
00099          <ref type="function">DB</ref>
00100          <ref type="application">DBdeltree</ref>
00101       </see-also>
00102    </function>
00103  ***/
00104 
00105 static int function_db_read(struct ast_channel *chan, const char *cmd,
00106              char *parse, char *buf, size_t len)
00107 {
00108    AST_DECLARE_APP_ARGS(args,
00109       AST_APP_ARG(family);
00110       AST_APP_ARG(key);
00111    );
00112 
00113    buf[0] = '\0';
00114 
00115    if (ast_strlen_zero(parse)) {
00116       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
00117       return -1;
00118    }
00119 
00120    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00121 
00122    if (args.argc < 2) {
00123       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
00124       return -1;
00125    }
00126 
00127    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00128       ast_debug(1, "DB: %s/%s not found in database.\n", args.family, args.key);
00129    } else {
00130       pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00131    }
00132 
00133    return 0;
00134 }
00135 
00136 static int function_db_write(struct ast_channel *chan, const char *cmd, char *parse,
00137               const char *value)
00138 {
00139    AST_DECLARE_APP_ARGS(args,
00140       AST_APP_ARG(family);
00141       AST_APP_ARG(key);
00142    );
00143 
00144    if (ast_strlen_zero(parse)) {
00145       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=<value>\n");
00146       return -1;
00147    }
00148 
00149    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00150 
00151    if (args.argc < 2) {
00152       ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=value\n");
00153       return -1;
00154    }
00155 
00156    if (ast_db_put(args.family, args.key, value)) {
00157       ast_log(LOG_WARNING, "DB: Error writing value to database.\n");
00158    }
00159 
00160    return 0;
00161 }
00162 
00163 static struct ast_custom_function db_function = {
00164    .name = "DB",
00165    .read = function_db_read,
00166    .write = function_db_write,
00167 };
00168 
00169 static int function_db_exists(struct ast_channel *chan, const char *cmd,
00170                char *parse, char *buf, size_t len)
00171 {
00172    AST_DECLARE_APP_ARGS(args,
00173       AST_APP_ARG(family);
00174       AST_APP_ARG(key);
00175    );
00176 
00177    buf[0] = '\0';
00178 
00179    if (ast_strlen_zero(parse)) {
00180       ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
00181       return -1;
00182    }
00183 
00184    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00185 
00186    if (args.argc < 2) {
00187       ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
00188       return -1;
00189    }
00190 
00191    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00192       strcpy(buf, "0");
00193    } else {
00194       pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00195       strcpy(buf, "1");
00196    }
00197 
00198    return 0;
00199 }
00200 
00201 static struct ast_custom_function db_exists_function = {
00202    .name = "DB_EXISTS",
00203    .read = function_db_exists,
00204 };
00205 
00206 static int function_db_delete(struct ast_channel *chan, const char *cmd,
00207                char *parse, char *buf, size_t len)
00208 {
00209    AST_DECLARE_APP_ARGS(args,
00210       AST_APP_ARG(family);
00211       AST_APP_ARG(key);
00212    );
00213 
00214    buf[0] = '\0';
00215 
00216    if (ast_strlen_zero(parse)) {
00217       ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
00218       return -1;
00219    }
00220 
00221    AST_NONSTANDARD_APP_ARGS(args, parse, '/');
00222 
00223    if (args.argc < 2) {
00224       ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
00225       return -1;
00226    }
00227 
00228    if (ast_db_get(args.family, args.key, buf, len - 1)) {
00229       ast_debug(1, "DB_DELETE: %s/%s not found in database.\n", args.family, args.key);
00230    } else {
00231       if (ast_db_del(args.family, args.key)) {
00232          ast_debug(1, "DB_DELETE: %s/%s could not be deleted from the database\n", args.family, args.key);
00233       }
00234    }
00235 
00236    pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
00237 
00238    return 0;
00239 }
00240 
00241 
00242 static struct ast_custom_function db_delete_function = {
00243    .name = "DB_DELETE",
00244    .read = function_db_delete,
00245 };
00246 
00247 static int unload_module(void)
00248 {
00249    int res = 0;
00250 
00251    res |= ast_custom_function_unregister(&db_function);
00252    res |= ast_custom_function_unregister(&db_exists_function);
00253    res |= ast_custom_function_unregister(&db_delete_function);
00254 
00255    return res;
00256 }
00257 
00258 static int load_module(void)
00259 {
00260    int res = 0;
00261 
00262    res |= ast_custom_function_register(&db_function);
00263    res |= ast_custom_function_register(&db_exists_function);
00264    res |= ast_custom_function_register(&db_delete_function);
00265 
00266    return res;
00267 }
00268 
00269 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Database (astdb) related dialplan functions");