Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


func_db.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005-2006, Russell Bryant <russelb@clemson.edu>
5  *
6  * func_db.c adapted from the old app_db.c, copyright by the following people
7  * Copyright (C) 2005, Mark Spencer <markster@digium.com>
8  * Copyright (C) 2003, Jefferson Noxon <jeff@debian.org>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20 
21 /*! \file
22  *
23  * \brief Functions for interaction with the Asterisk database
24  *
25  * \author Russell Bryant <russelb@clemson.edu>
26  *
27  * \ingroup functions
28  */
29 
30 /*** MODULEINFO
31  <support_level>core</support_level>
32  ***/
33 
34 #include "asterisk.h"
35 
36 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 428431 $")
37 
38 #include <regex.h>
39 
40 #include "asterisk/module.h"
41 #include "asterisk/channel.h"
42 #include "asterisk/pbx.h"
43 #include "asterisk/utils.h"
44 #include "asterisk/app.h"
45 #include "asterisk/astdb.h"
46 
47 /*** DOCUMENTATION
48  <function name="DB" language="en_US">
49  <synopsis>
50  Read from or write to the Asterisk database.
51  </synopsis>
52  <syntax argsep="/">
53  <parameter name="family" required="true" />
54  <parameter name="key" required="true" />
55  </syntax>
56  <description>
57  <para>This function will read from or write a value to the Asterisk database. On a
58  read, this function returns the corresponding value from the database, or blank
59  if it does not exist. Reading a database value will also set the variable
60  DB_RESULT. If you wish to find out if an entry exists, use the DB_EXISTS
61  function.</para>
62  </description>
63  <see-also>
64  <ref type="application">DBdel</ref>
65  <ref type="function">DB_DELETE</ref>
66  <ref type="application">DBdeltree</ref>
67  <ref type="function">DB_EXISTS</ref>
68  </see-also>
69  </function>
70  <function name="DB_EXISTS" language="en_US">
71  <synopsis>
72  Check to see if a key exists in the Asterisk database.
73  </synopsis>
74  <syntax argsep="/">
75  <parameter name="family" required="true" />
76  <parameter name="key" required="true" />
77  </syntax>
78  <description>
79  <para>This function will check to see if a key exists in the Asterisk
80  database. If it exists, the function will return <literal>1</literal>. If not,
81  it will return <literal>0</literal>. Checking for existence of a database key will
82  also set the variable DB_RESULT to the key's value if it exists.</para>
83  </description>
84  <see-also>
85  <ref type="function">DB</ref>
86  </see-also>
87  </function>
88  <function name="DB_DELETE" language="en_US">
89  <synopsis>
90  Return a value from the database and delete it.
91  </synopsis>
92  <syntax argsep="/">
93  <parameter name="family" required="true" />
94  <parameter name="key" required="true" />
95  </syntax>
96  <description>
97  <para>This function will retrieve a value from the Asterisk database
98  and then remove that key from the database. <variable>DB_RESULT</variable>
99  will be set to the key's value if it exists.</para>
100  <note>
101  <para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
102  is set to <literal>no</literal>, this function can only be read from the
103  dialplan, and not directly from external protocols. It can, however, be
104  executed as a write operation (<literal>DB_DELETE(family, key)=ignored</literal>)</para>
105  </note>
106  </description>
107  <see-also>
108  <ref type="application">DBdel</ref>
109  <ref type="function">DB</ref>
110  <ref type="application">DBdeltree</ref>
111  </see-also>
112  </function>
113  ***/
114 
115 static int function_db_read(struct ast_channel *chan, const char *cmd,
116  char *parse, char *buf, size_t len)
117 {
119  AST_APP_ARG(family);
120  AST_APP_ARG(key);
121  );
122 
123  buf[0] = '\0';
124 
125  if (ast_strlen_zero(parse)) {
126  ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
127  return -1;
128  }
129 
130  AST_NONSTANDARD_APP_ARGS(args, parse, '/');
131 
132  if (args.argc < 2) {
133  ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)\n");
134  return -1;
135  }
136 
137  if (ast_db_get(args.family, args.key, buf, len - 1)) {
138  ast_debug(1, "DB: %s/%s not found in database.\n", args.family, args.key);
139  } else {
140  pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
141  }
142 
143  return 0;
144 }
145 
146 static int function_db_write(struct ast_channel *chan, const char *cmd, char *parse,
147  const char *value)
148 {
150  AST_APP_ARG(family);
151  AST_APP_ARG(key);
152  );
153 
154  if (ast_strlen_zero(parse)) {
155  ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=<value>\n");
156  return -1;
157  }
158 
159  AST_NONSTANDARD_APP_ARGS(args, parse, '/');
160 
161  if (args.argc < 2) {
162  ast_log(LOG_WARNING, "DB requires an argument, DB(<family>/<key>)=value\n");
163  return -1;
164  }
165 
166  if (ast_db_put(args.family, args.key, value)) {
167  ast_log(LOG_WARNING, "DB: Error writing value to database.\n");
168  }
169 
170  return 0;
171 }
172 
174  .name = "DB",
175  .read = function_db_read,
176  .write = function_db_write,
177 };
178 
179 static int function_db_exists(struct ast_channel *chan, const char *cmd,
180  char *parse, char *buf, size_t len)
181 {
183  AST_APP_ARG(family);
184  AST_APP_ARG(key);
185  );
186 
187  buf[0] = '\0';
188 
189  if (ast_strlen_zero(parse)) {
190  ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
191  return -1;
192  }
193 
194  AST_NONSTANDARD_APP_ARGS(args, parse, '/');
195 
196  if (args.argc < 2) {
197  ast_log(LOG_WARNING, "DB_EXISTS requires an argument, DB(<family>/<key>)\n");
198  return -1;
199  }
200 
201  if (ast_db_get(args.family, args.key, buf, len - 1)) {
202  strcpy(buf, "0");
203  } else {
204  pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
205  strcpy(buf, "1");
206  }
207 
208  return 0;
209 }
210 
212  .name = "DB_EXISTS",
213  .read = function_db_exists,
214  .read_max = 2,
215 };
216 
217 static int function_db_delete(struct ast_channel *chan, const char *cmd,
218  char *parse, char *buf, size_t len)
219 {
221  AST_APP_ARG(family);
222  AST_APP_ARG(key);
223  );
224 
225  buf[0] = '\0';
226 
227  if (ast_strlen_zero(parse)) {
228  ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
229  return -1;
230  }
231 
232  AST_NONSTANDARD_APP_ARGS(args, parse, '/');
233 
234  if (args.argc < 2) {
235  ast_log(LOG_WARNING, "DB_DELETE requires an argument, DB_DELETE(<family>/<key>)\n");
236  return -1;
237  }
238 
239  if (ast_db_get(args.family, args.key, buf, len - 1)) {
240  ast_debug(1, "DB_DELETE: %s/%s not found in database.\n", args.family, args.key);
241  } else {
242  if (ast_db_del(args.family, args.key)) {
243  ast_debug(1, "DB_DELETE: %s/%s could not be deleted from the database\n", args.family, args.key);
244  }
245  }
246 
247  pbx_builtin_setvar_helper(chan, "DB_RESULT", buf);
248 
249  return 0;
250 }
251 
252 /*!
253  * \brief Wrapper to execute DB_DELETE from a write operation. Allows execution
254  * even if live_dangerously is disabled.
255  */
256 static int function_db_delete_write(struct ast_channel *chan, const char *cmd, char *parse,
257  const char *value)
258 {
259  /* Throwaway to hold the result from the read */
260  char buf[128];
261  return function_db_delete(chan, cmd, parse, buf, sizeof(buf));
262 }
263 
265  .name = "DB_DELETE",
266  .read = function_db_delete,
267  .write = function_db_delete_write,
268 };
269 
270 static int unload_module(void)
271 {
272  int res = 0;
273 
274  res |= ast_custom_function_unregister(&db_function);
275  res |= ast_custom_function_unregister(&db_exists_function);
276  res |= ast_custom_function_unregister(&db_delete_function);
277 
278  return res;
279 }
280 
281 static int load_module(void)
282 {
283  int res = 0;
284 
286  res |= ast_custom_function_register(&db_exists_function);
287  res |= ast_custom_function_register_escalating(&db_delete_function, AST_CFE_READ);
288 
289  return res;
290 }
291 
292 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Database (astdb) related dialplan functions");
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:396
Asterisk main include file. File version handling, generic pbx functions.
int ast_db_get(const char *family, const char *key, char *out, int outlen)
Get key value specified by family/key.
Definition: db.c:348
#define LOG_WARNING
Definition: logger.h:144
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;s arguments.
Definition: app.h:572
static struct ast_custom_function db_delete_function
Definition: func_db.c:264
int value
Definition: syslog.c:39
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx.c:3814
Utility functions.
#define ast_custom_function_register_escalating(acf, escalation)
Register a custom function which requires escalated privileges.
Definition: pbx.h:1173
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
static int function_db_exists(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_db.c:179
static int function_db_write(struct ast_channel *chan, const char *cmd, char *parse, const char *value)
Definition: func_db.c:146
General Asterisk PBX channel definitions.
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
Data structure associated with a custom dialplan function.
Definition: pbx.h:95
static int function_db_delete(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_db.c:217
static int function_db_delete_write(struct ast_channel *chan, const char *cmd, char *parse, const char *value)
Wrapper to execute DB_DELETE from a write operation. Allows execution even if live_dangerously is dis...
Definition: func_db.c:256
Core PBX routines and definitions.
static int unload_module(void)
Definition: func_db.c:270
static struct @350 args
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static void parse(struct mgcp_request *req)
Definition: chan_mgcp.c:1858
static int load_module(void)
Definition: func_db.c:281
static struct ast_custom_function db_exists_function
Definition: func_db.c:211
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name...
Definition: pbx.c:10546
int ast_db_del(const char *family, const char *key)
Delete entry in astdb.
Definition: db.c:365
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
const char * name
Definition: pbx.h:96
int ast_db_put(const char *family, const char *key, const char *value)
Store value addressed by family/key.
Definition: db.c:260
#define AST_APP_ARG(name)
Define an application argument.
Definition: app.h:555
#define AST_NONSTANDARD_APP_ARGS(args, parse, sep)
Performs the &#39;nonstandard&#39; argument separation process for an application.
Definition: app.h:619
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:38
static int function_db_read(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_db.c:115
Asterisk module definitions.
Persistant data storage (akin to *doze registry)
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1164
static struct ast_custom_function db_function
Definition: func_db.c:173
#define ASTERISK_FILE_VERSION(file, version)
Register/unregister a source code file with the core.
Definition: asterisk.h:180