Multiple revisions 369001-369002
[asterisk/asterisk.git] / funcs / func_realtime.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005-2006, BJ Weschke. All rights reserved.
5  * 
6  * BJ Weschke <bweschke@btwtech.com>
7  * 
8  * This code is released by the author with no restrictions on usage. 
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  */
17
18 /*! \file
19  *
20  * \brief REALTIME dialplan function
21  * 
22  * \author BJ Weschke <bweschke@btwtech.com>
23  * 
24  * \ingroup functions
25  */
26
27 /*** MODULEINFO
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
34
35 #include "asterisk/file.h"
36 #include "asterisk/channel.h"
37 #include "asterisk/pbx.h"
38 #include "asterisk/config.h"
39 #include "asterisk/module.h"
40 #include "asterisk/lock.h"
41 #include "asterisk/utils.h"
42 #include "asterisk/app.h"
43
44 /*** DOCUMENTATION
45         <function name="REALTIME" language="en_US">
46                 <synopsis>
47                         RealTime Read/Write Functions.
48                 </synopsis>
49                 <syntax>
50                         <parameter name="family" required="true" />
51                         <parameter name="fieldmatch" required="true" />
52                         <parameter name="value" />
53                         <parameter name="delim1|field">
54                                 <para>Use <replaceable>delim1</replaceable> with <replaceable>delim2</replaceable> on
55                                 read and <replaceable>field</replaceable> without <replaceable>delim2</replaceable> on
56                                 write</para>
57                                 <para>If we are reading and <replaceable>delim1</replaceable> is not specified, defaults
58                                 to <literal>,</literal></para>
59                         </parameter>
60                         <parameter name="delim2">
61                                 <para>Parameter only used when reading, if not specified defaults to <literal>=</literal></para>
62                         </parameter>
63                 </syntax>
64                 <description>
65                         <para>This function will read or write values from/to a RealTime repository.
66                         REALTIME(....) will read names/values from the repository, and 
67                         REALTIME(....)= will write a new value/field to the repository. On a
68                         read, this function returns a delimited text string. The name/value
69                         pairs are delimited by <replaceable>delim1</replaceable>, and the name and value are delimited
70                         between each other with delim2. 
71                         If there is no match, NULL will be returned by the function.
72                         On a write, this function will always return NULL.</para>
73                 </description>
74                 <see-also>
75                         <ref type="function">REALTIME_STORE</ref>
76                         <ref type="function">REALTIME_DESTROY</ref>
77                         <ref type="function">REALTIME_FIELD</ref>
78                         <ref type="function">REALTIME_HASH</ref>
79                 </see-also>
80         </function>
81         <function name="REALTIME_STORE" language="en_US">
82                 <synopsis>
83                         RealTime Store Function.
84                 </synopsis>
85                 <syntax>
86                         <parameter name="family" required="true" />
87                         <parameter name="field1" required="true" />
88                         <parameter name="fieldN" required="true" multiple="true" />
89                         <parameter name="field30" required="true" />
90                 </syntax>
91                 <description>
92                         <para>This function will insert a new set of values into the RealTime repository.
93                         If RT engine provides an unique ID of the stored record, REALTIME_STORE(...)=..
94                         creates channel variable named RTSTOREID, which contains value of unique ID.
95                         Currently, a maximum of 30 field/value pairs is supported.</para>
96                 </description>
97                 <see-also>
98                         <ref type="function">REALTIME</ref>
99                         <ref type="function">REALTIME_DESTROY</ref>
100                         <ref type="function">REALTIME_FIELD</ref>
101                         <ref type="function">REALTIME_HASH</ref>
102                 </see-also>
103         </function>
104         <function name="REALTIME_DESTROY" language="en_US">
105                 <synopsis>
106                         RealTime Destroy Function.
107                 </synopsis>
108                 <syntax>
109                         <parameter name="family" required="true" />
110                         <parameter name="fieldmatch" required="true" />
111                         <parameter name="value" />
112                         <parameter name="delim1" />
113                         <parameter name="delim2" />
114                 </syntax>
115                 <description>
116                         <para>This function acts in the same way as REALTIME(....) does, except that
117                         it destroys the matched record in the RT engine.</para>
118                 </description>
119                 <see-also>
120                         <ref type="function">REALTIME</ref>
121                         <ref type="function">REALTIME_STORE</ref>
122                         <ref type="function">REALTIME_FIELD</ref>
123                         <ref type="function">REALTIME_HASH</ref>
124                 </see-also>
125         </function>
126         <function name="REALTIME_FIELD" language="en_US">
127                 <synopsis>
128                         RealTime query function.
129                 </synopsis>
130                 <syntax>
131                         <parameter name="family" required="true" />
132                         <parameter name="fieldmatch" required="true" />
133                         <parameter name="value" required="true" />
134                         <parameter name="fieldname" required="true" />
135                 </syntax>
136                 <description>
137                         <para>This function retrieves a single item, <replaceable>fieldname</replaceable>
138                         from the RT engine, where <replaceable>fieldmatch</replaceable> contains the value
139                         <replaceable>value</replaceable>.  When written to, the REALTIME_FIELD() function
140                         performs identically to the REALTIME() function.</para>
141                 </description>
142                 <see-also>
143                         <ref type="function">REALTIME</ref>
144                         <ref type="function">REALTIME_STORE</ref>
145                         <ref type="function">REALTIME_DESTROY</ref>
146                         <ref type="function">REALTIME_HASH</ref>
147                 </see-also>
148         </function>
149         <function name="REALTIME_HASH" language="en_US">
150                 <synopsis>
151                         RealTime query function.
152                 </synopsis>
153                 <syntax>
154                         <parameter name="family" required="true" />
155                         <parameter name="fieldmatch" required="true" />
156                         <parameter name="value" required="true" />
157                 </syntax>
158                 <description>
159                         <para>This function retrieves a single record from the RT engine, where
160                         <replaceable>fieldmatch</replaceable> contains the value
161                         <replaceable>value</replaceable> and formats the output suitably, such that
162                         it can be assigned to the HASH() function.  The HASH() function then provides
163                         a suitable method for retrieving each field value of the record.</para>
164                 </description>
165                 <see-also>
166                         <ref type="function">REALTIME</ref>
167                         <ref type="function">REALTIME_STORE</ref>
168                         <ref type="function">REALTIME_DESTROY</ref>
169                         <ref type="function">REALTIME_FIELD</ref>
170                 </see-also>
171         </function>
172  ***/
173
174 AST_THREADSTORAGE(buf1);
175 AST_THREADSTORAGE(buf2);
176 AST_THREADSTORAGE(buf3);
177
178 static int function_realtime_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
179 {
180         struct ast_variable *var, *head;
181         struct ast_str *out;
182         size_t resultslen;
183         int n;
184         AST_DECLARE_APP_ARGS(args,
185                 AST_APP_ARG(family);
186                 AST_APP_ARG(fieldmatch);
187                 AST_APP_ARG(value);
188                 AST_APP_ARG(delim1);
189                 AST_APP_ARG(delim2);
190         );
191
192         if (ast_strlen_zero(data)) {
193                 ast_log(LOG_WARNING, "Syntax: REALTIME(family,fieldmatch[,value[,delim1[,delim2]]]) - missing argument!\n");
194                 return -1;
195         }
196
197         AST_STANDARD_APP_ARGS(args, data);
198
199         if (!args.delim1)
200                 args.delim1 = ",";
201         if (!args.delim2)
202                 args.delim2 = "=";
203
204         if (chan)
205                 ast_autoservice_start(chan);
206
207         head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL);
208
209         if (!head) {
210                 if (chan)
211                         ast_autoservice_stop(chan);
212                 return -1;
213         }
214
215         resultslen = 0;
216         n = 0;
217         for (var = head; var; n++, var = var->next)
218                 resultslen += strlen(var->name) + strlen(var->value);
219         /* add space for delimiters and final '\0' */
220         resultslen += n * (strlen(args.delim1) + strlen(args.delim2)) + 1;
221
222         out = ast_str_alloca(resultslen);
223         for (var = head; var; var = var->next)
224                 ast_str_append(&out, 0, "%s%s%s%s", var->name, args.delim2, var->value, args.delim1);
225         ast_copy_string(buf, ast_str_buffer(out), len);
226
227         ast_variables_destroy(head);
228
229         if (chan)
230                 ast_autoservice_stop(chan);
231
232         return 0;
233 }
234
235 static int function_realtime_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
236 {
237         int res = 0;
238         AST_DECLARE_APP_ARGS(args,
239                 AST_APP_ARG(family);
240                 AST_APP_ARG(fieldmatch);
241                 AST_APP_ARG(value);
242                 AST_APP_ARG(field);
243         );
244
245         if (ast_strlen_zero(data)) {
246                 ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value,newcol) - missing argument!\n", cmd);
247                 return -1;
248         }
249
250         if (chan)
251                 ast_autoservice_start(chan);
252
253         AST_STANDARD_APP_ARGS(args, data);
254
255         res = ast_update_realtime(args.family, args.fieldmatch, args.value, args.field, (char *)value, SENTINEL);
256
257         if (res < 0) {
258                 ast_log(LOG_WARNING, "Failed to update. Check the debug log for possible data repository related entries.\n");
259         }
260
261         if (chan)
262                 ast_autoservice_stop(chan);
263
264         return 0;
265 }
266
267 static int realtimefield_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
268 {
269         struct ast_variable *var, *head;
270         struct ast_str *escapebuf = ast_str_thread_get(&buf1, 16);
271         struct ast_str *fields = ast_str_thread_get(&buf2, 16);
272         struct ast_str *values = ast_str_thread_get(&buf3, 16);
273         int first = 0;
274         enum { rtfield, rthash } which;
275         AST_DECLARE_APP_ARGS(args,
276                 AST_APP_ARG(family);
277                 AST_APP_ARG(fieldmatch);
278                 AST_APP_ARG(value);
279                 AST_APP_ARG(fieldname);
280         );
281
282         if (!strcmp(cmd, "REALTIME_FIELD")) {
283                 which = rtfield;
284         } else {
285                 which = rthash;
286         }
287
288         if (ast_strlen_zero(data)) {
289                 ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value%s) - missing argument!\n", cmd, which == rtfield ? ",fieldname" : "");
290                 return -1;
291         }
292
293         AST_STANDARD_APP_ARGS(args, data);
294
295         if ((which == rtfield && args.argc != 4) || (which == rthash && args.argc != 3)) {
296                 ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value%s) - missing argument!\n", cmd, which == rtfield ? ",fieldname" : "");
297                 return -1;
298         }
299
300         if (chan) {
301                 ast_autoservice_start(chan);
302         }
303
304         if (!(head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL))) {
305                 if (chan) {
306                         ast_autoservice_stop(chan);
307                 }
308                 return -1;
309         }
310
311         ast_str_reset(fields);
312         ast_str_reset(values);
313
314         for (var = head; var; var = var->next) {
315                 if (which == rtfield) {
316                         ast_debug(1, "Comparing %s to %s\n", var->name, args.fieldname);
317                         if (!strcasecmp(var->name, args.fieldname)) {
318                                 ast_debug(1, "Match! Value is %s\n", var->value);
319                                 ast_copy_string(buf, var->value, len);
320                                 break;
321                         }
322                 } else if (which == rthash) {
323                         ast_debug(1, "Setting hash key %s to value %s\n", var->name, var->value);
324                         ast_str_append(&fields, 0, "%s%s", first ? "" : ",", ast_str_set_escapecommas(&escapebuf, 0, var->name, INT_MAX));
325                         ast_str_append(&values, 0, "%s%s", first ? "" : ",", ast_str_set_escapecommas(&escapebuf, 0, var->value, INT_MAX));
326                         first = 0;
327                 }
328         }
329         ast_variables_destroy(head);
330
331         if (which == rthash) {
332                 pbx_builtin_setvar_helper(chan, "~ODBCFIELDS~", ast_str_buffer(fields));
333                 ast_copy_string(buf, ast_str_buffer(values), len);
334         }
335
336         if (chan) {
337                 ast_autoservice_stop(chan);
338         }
339
340         return 0;
341 }
342
343 static int function_realtime_store(struct ast_channel *chan, const char *cmd, char *data, const char *value)
344 {
345         int res = 0;
346         char storeid[32];
347         char *valcopy;
348         AST_DECLARE_APP_ARGS(a,
349                 AST_APP_ARG(family);
350                 AST_APP_ARG(f)[30]; /* fields */
351         );
352
353         AST_DECLARE_APP_ARGS(v,
354                 AST_APP_ARG(v)[30]; /* values */
355         );
356
357         if (ast_strlen_zero(data)) {
358                 ast_log(LOG_WARNING, "Syntax: REALTIME_STORE(family,field1,field2,...,field30) - missing argument!\n");
359                 return -1;
360         }
361
362         if (chan)
363                 ast_autoservice_start(chan);
364
365         valcopy = ast_strdupa(value);
366         AST_STANDARD_APP_ARGS(a, data);
367         AST_STANDARD_APP_ARGS(v, valcopy);
368
369         res = ast_store_realtime(a.family, 
370                 a.f[0], v.v[0], a.f[1], v.v[1], a.f[2], v.v[2], a.f[3], v.v[3], a.f[4], v.v[4],
371                 a.f[5], v.v[5], a.f[6], v.v[6], a.f[7], v.v[7], a.f[8], v.v[8], a.f[9], v.v[9],
372                 a.f[10], v.v[10], a.f[11], v.v[11], a.f[12], v.v[12], a.f[13], v.v[13], a.f[14], v.v[14],
373                 a.f[15], v.v[15], a.f[16], v.v[16], a.f[17], v.v[17], a.f[18], v.v[18], a.f[19], v.v[19],
374                 a.f[20], v.v[20], a.f[21], v.v[21], a.f[22], v.v[22], a.f[23], v.v[23], a.f[24], v.v[24],
375                 a.f[25], v.v[25], a.f[26], v.v[26], a.f[27], v.v[27], a.f[28], v.v[28], a.f[29], v.v[29], SENTINEL
376         );
377
378         if (res < 0) {
379                 ast_log(LOG_WARNING, "Failed to store. Check the debug log for possible data repository related entries.\n");
380         } else {
381                 snprintf(storeid, sizeof(storeid), "%d", res);
382                 pbx_builtin_setvar_helper(chan, "RTSTOREID", storeid);
383         }
384
385         if (chan)
386                 ast_autoservice_stop(chan);
387
388         return 0;
389 }
390
391 static int function_realtime_readdestroy(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
392 {
393         struct ast_variable *var, *head;
394         struct ast_str *out;
395         size_t resultslen;
396         int n;
397         AST_DECLARE_APP_ARGS(args,
398                 AST_APP_ARG(family);
399                 AST_APP_ARG(fieldmatch);
400                 AST_APP_ARG(value);
401                 AST_APP_ARG(delim1);
402                 AST_APP_ARG(delim2);
403         );
404
405         if (ast_strlen_zero(data)) {
406                 ast_log(LOG_WARNING, "Syntax: REALTIME_DESTROY(family,fieldmatch[,value[,delim1[,delim2]]]) - missing argument!\n");
407                 return -1;
408         }
409
410         AST_STANDARD_APP_ARGS(args, data);
411
412         if (!args.delim1)
413                 args.delim1 = ",";
414         if (!args.delim2)
415                 args.delim2 = "=";
416
417         if (chan)
418                 ast_autoservice_start(chan);
419
420         head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL);
421
422         if (!head) {
423                 if (chan)
424                         ast_autoservice_stop(chan);
425                 return -1;
426         }
427
428         resultslen = 0;
429         n = 0;
430         for (var = head; var; n++, var = var->next)
431                 resultslen += strlen(var->name) + strlen(var->value);
432         /* add space for delimiters and final '\0' */
433         resultslen += n * (strlen(args.delim1) + strlen(args.delim2)) + 1;
434
435         out = ast_str_alloca(resultslen);
436         for (var = head; var; var = var->next) {
437                 ast_str_append(&out, 0, "%s%s%s%s", var->name, args.delim2, var->value, args.delim1);
438         }
439         ast_copy_string(buf, ast_str_buffer(out), len);
440
441         ast_destroy_realtime(args.family, args.fieldmatch, args.value, SENTINEL);
442         ast_variables_destroy(head);
443
444         if (chan)
445                 ast_autoservice_stop(chan);
446
447         return 0;
448 }
449
450 static struct ast_custom_function realtime_function = {
451         .name = "REALTIME",
452         .read = function_realtime_read,
453         .write = function_realtime_write,
454 };
455
456 static struct ast_custom_function realtimefield_function = {
457         .name = "REALTIME_FIELD",
458         .read = realtimefield_read,
459         .write = function_realtime_write,
460 };
461
462 static struct ast_custom_function realtimehash_function = {
463         .name = "REALTIME_HASH",
464         .read = realtimefield_read,
465 };
466
467 static struct ast_custom_function realtime_store_function = {
468         .name = "REALTIME_STORE",
469         .write = function_realtime_store,
470 };
471
472 static struct ast_custom_function realtime_destroy_function = {
473         .name = "REALTIME_DESTROY",
474         .read = function_realtime_readdestroy,
475 };
476
477 static int unload_module(void)
478 {
479         int res = 0;
480         res |= ast_custom_function_unregister(&realtime_function);
481         res |= ast_custom_function_unregister(&realtime_store_function);
482         res |= ast_custom_function_unregister(&realtime_destroy_function);
483         res |= ast_custom_function_unregister(&realtimefield_function);
484         res |= ast_custom_function_unregister(&realtimehash_function);
485         return res;
486 }
487
488 static int load_module(void)
489 {
490         int res = 0;
491         res |= ast_custom_function_register(&realtime_function);
492         res |= ast_custom_function_register(&realtime_store_function);
493         res |= ast_custom_function_register(&realtime_destroy_function);
494         res |= ast_custom_function_register(&realtimefield_function);
495         res |= ast_custom_function_register(&realtimehash_function);
496         return res;
497 }
498
499 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Read/Write/Store/Destroy values from a RealTime repository");