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