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