Mon Jun 27 16:50:54 2011

Asterisk developer's documentation


func_realtime.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2005-2006, BJ Weschke. All rights reserved.
00005  * 
00006  * BJ Weschke <bweschke@btwtech.com>
00007  * 
00008  * This code is released by the author with no restrictions on usage. 
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  */
00017 
00018 /*! \file
00019  *
00020  * \brief REALTIME dialplan function
00021  * 
00022  * \author BJ Weschke <bweschke@btwtech.com>
00023  * 
00024  * \ingroup functions
00025  */
00026 
00027 #include "asterisk.h"
00028 
00029 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 304908 $")
00030 
00031 #include "asterisk/file.h"
00032 #include "asterisk/channel.h"
00033 #include "asterisk/pbx.h"
00034 #include "asterisk/config.h"
00035 #include "asterisk/module.h"
00036 #include "asterisk/lock.h"
00037 #include "asterisk/utils.h"
00038 #include "asterisk/app.h"
00039 
00040 /*** DOCUMENTATION
00041    <function name="REALTIME" language="en_US">
00042       <synopsis>
00043          RealTime Read/Write Functions.
00044       </synopsis>
00045       <syntax>
00046          <parameter name="family" required="true" />
00047          <parameter name="fieldmatch" required="true" />
00048          <parameter name="value" />
00049          <parameter name="delim1|field">
00050             <para>Use <replaceable>delim1</replaceable> with <replaceable>delim2</replaceable> on
00051             read and <replaceable>field</replaceable> without <replaceable>delim2</replaceable> on
00052             write</para>
00053             <para>If we are reading and <replaceable>delim1</replaceable> is not specified, defaults
00054             to <literal>,</literal></para>
00055          </parameter>
00056          <parameter name="delim2">
00057             <para>Parameter only used when reading, if not specified defaults to <literal>=</literal></para>
00058          </parameter>
00059       </syntax>
00060       <description>
00061          <para>This function will read or write values from/to a RealTime repository.
00062          REALTIME(....) will read names/values from the repository, and 
00063          REALTIME(....)= will write a new value/field to the repository. On a
00064          read, this function returns a delimited text string. The name/value
00065          pairs are delimited by <replaceable>delim1</replaceable>, and the name and value are delimited
00066          between each other with delim2. 
00067          If there is no match, NULL will be returned by the function.
00068          On a write, this function will always return NULL.</para>
00069       </description>
00070       <see-also>
00071          <ref type="function">REALTIME_STORE</ref>
00072          <ref type="function">REALTIME_DESTROY</ref>
00073          <ref type="function">REALTIME_FIELD</ref>
00074          <ref type="function">REALTIME_HASH</ref>
00075       </see-also>
00076    </function>
00077    <function name="REALTIME_STORE" language="en_US">
00078       <synopsis>
00079          RealTime Store Function.
00080       </synopsis>
00081       <syntax>
00082          <parameter name="family" required="true" />
00083          <parameter name="field1" required="true" />
00084          <parameter name="fieldN" required="true" multiple="true" />
00085          <parameter name="field30" required="true" />
00086       </syntax>
00087       <description>
00088          <para>This function will insert a new set of values into the RealTime repository.
00089          If RT engine provides an unique ID of the stored record, REALTIME_STORE(...)=..
00090          creates channel variable named RTSTOREID, which contains value of unique ID.
00091          Currently, a maximum of 30 field/value pairs is supported.</para>
00092       </description>
00093       <see-also>
00094          <ref type="function">REALTIME</ref>
00095          <ref type="function">REALTIME_DESTROY</ref>
00096          <ref type="function">REALTIME_FIELD</ref>
00097          <ref type="function">REALTIME_HASH</ref>
00098       </see-also>
00099    </function>
00100    <function name="REALTIME_DESTROY" language="en_US">
00101       <synopsis>
00102          RealTime Destroy Function.
00103       </synopsis>
00104       <syntax>
00105          <parameter name="family" required="true" />
00106          <parameter name="fieldmatch" required="true" />
00107          <parameter name="value" />
00108          <parameter name="delim1" />
00109          <parameter name="delim2" />
00110       </syntax>
00111       <description>
00112          <para>This function acts in the same way as REALTIME(....) does, except that
00113          it destroys the matched record in the RT engine.</para>
00114       </description>
00115       <see-also>
00116          <ref type="function">REALTIME</ref>
00117          <ref type="function">REALTIME_STORE</ref>
00118          <ref type="function">REALTIME_FIELD</ref>
00119          <ref type="function">REALTIME_HASH</ref>
00120       </see-also>
00121    </function>
00122    <function name="REALTIME_FIELD" language="en_US">
00123       <synopsis>
00124          RealTime query function.
00125       </synopsis>
00126       <syntax>
00127          <parameter name="family" required="true" />
00128          <parameter name="fieldmatch" required="true" />
00129          <parameter name="value" required="true" />
00130          <parameter name="fieldname" required="true" />
00131       </syntax>
00132       <description>
00133          <para>This function retrieves a single item, <replaceable>fieldname</replaceable>
00134          from the RT engine, where <replaceable>fieldmatch</replaceable> contains the value
00135          <replaceable>value</replaceable>.  When written to, the REALTIME_FIELD() function
00136          performs identically to the REALTIME() function.</para>
00137       </description>
00138       <see-also>
00139          <ref type="function">REALTIME</ref>
00140          <ref type="function">REALTIME_STORE</ref>
00141          <ref type="function">REALTIME_DESTROY</ref>
00142          <ref type="function">REALTIME_HASH</ref>
00143       </see-also>
00144    </function>
00145    <function name="REALTIME_HASH" language="en_US">
00146       <synopsis>
00147          RealTime query function.
00148       </synopsis>
00149       <syntax>
00150          <parameter name="family" required="true" />
00151          <parameter name="fieldmatch" required="true" />
00152          <parameter name="value" required="true" />
00153       </syntax>
00154       <description>
00155          <para>This function retrieves a single record from the RT engine, where
00156          <replaceable>fieldmatch</replaceable> contains the value
00157          <replaceable>value</replaceable> and formats the output suitably, such that
00158          it can be assigned to the HASH() function.  The HASH() function then provides
00159          a suitable method for retrieving each field value of the record.</para>
00160       </description>
00161       <see-also>
00162          <ref type="function">REALTIME</ref>
00163          <ref type="function">REALTIME_STORE</ref>
00164          <ref type="function">REALTIME_DESTROY</ref>
00165          <ref type="function">REALTIME_FIELD</ref>
00166       </see-also>
00167    </function>
00168  ***/
00169 
00170 AST_THREADSTORAGE(buf1);
00171 AST_THREADSTORAGE(buf2);
00172 AST_THREADSTORAGE(buf3);
00173 
00174 static int function_realtime_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
00175 {
00176    struct ast_variable *var, *head;
00177    struct ast_str *out;
00178    size_t resultslen;
00179    int n;
00180    AST_DECLARE_APP_ARGS(args,
00181       AST_APP_ARG(family);
00182       AST_APP_ARG(fieldmatch);
00183       AST_APP_ARG(value);
00184       AST_APP_ARG(delim1);
00185       AST_APP_ARG(delim2);
00186    );
00187 
00188    if (ast_strlen_zero(data)) {
00189       ast_log(LOG_WARNING, "Syntax: REALTIME(family,fieldmatch[,value[,delim1[,delim2]]]) - missing argument!\n");
00190       return -1;
00191    }
00192 
00193    AST_STANDARD_APP_ARGS(args, data);
00194 
00195    if (!args.delim1)
00196       args.delim1 = ",";
00197    if (!args.delim2)
00198       args.delim2 = "=";
00199 
00200    if (chan)
00201       ast_autoservice_start(chan);
00202 
00203    head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL);
00204 
00205    if (!head) {
00206       if (chan)
00207          ast_autoservice_stop(chan);
00208       return -1;
00209    }
00210 
00211    resultslen = 0;
00212    n = 0;
00213    for (var = head; var; n++, var = var->next)
00214       resultslen += strlen(var->name) + strlen(var->value);
00215    /* add space for delimiters and final '\0' */
00216    resultslen += n * (strlen(args.delim1) + strlen(args.delim2)) + 1;
00217 
00218    out = ast_str_alloca(resultslen);
00219    for (var = head; var; var = var->next)
00220       ast_str_append(&out, 0, "%s%s%s%s", var->name, args.delim2, var->value, args.delim1);
00221    ast_copy_string(buf, ast_str_buffer(out), len);
00222 
00223    ast_variables_destroy(head);
00224 
00225    if (chan)
00226       ast_autoservice_stop(chan);
00227 
00228    return 0;
00229 }
00230 
00231 static int function_realtime_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
00232 {
00233    int res = 0;
00234    AST_DECLARE_APP_ARGS(args,
00235       AST_APP_ARG(family);
00236       AST_APP_ARG(fieldmatch);
00237       AST_APP_ARG(value);
00238       AST_APP_ARG(field);
00239    );
00240 
00241    if (ast_strlen_zero(data)) {
00242       ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value,newcol) - missing argument!\n", cmd);
00243       return -1;
00244    }
00245 
00246    if (chan)
00247       ast_autoservice_start(chan);
00248 
00249    AST_STANDARD_APP_ARGS(args, data);
00250 
00251    res = ast_update_realtime(args.family, args.fieldmatch, args.value, args.field, (char *)value, SENTINEL);
00252 
00253    if (res < 0) {
00254       ast_log(LOG_WARNING, "Failed to update. Check the debug log for possible data repository related entries.\n");
00255    }
00256 
00257    if (chan)
00258       ast_autoservice_stop(chan);
00259 
00260    return 0;
00261 }
00262 
00263 static int realtimefield_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
00264 {
00265    struct ast_variable *var, *head;
00266    struct ast_str *escapebuf = ast_str_thread_get(&buf1, 16);
00267    struct ast_str *fields = ast_str_thread_get(&buf2, 16);
00268    struct ast_str *values = ast_str_thread_get(&buf3, 16);
00269    int first = 0;
00270    enum { rtfield, rthash } which;
00271    AST_DECLARE_APP_ARGS(args,
00272       AST_APP_ARG(family);
00273       AST_APP_ARG(fieldmatch);
00274       AST_APP_ARG(value);
00275       AST_APP_ARG(fieldname);
00276    );
00277 
00278    if (!strcmp(cmd, "REALTIME_FIELD")) {
00279       which = rtfield;
00280    } else {
00281       which = rthash;
00282    }
00283 
00284    if (ast_strlen_zero(data)) {
00285       ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value%s) - missing argument!\n", cmd, which == rtfield ? ",fieldname" : "");
00286       return -1;
00287    }
00288 
00289    AST_STANDARD_APP_ARGS(args, data);
00290 
00291    if ((which == rtfield && args.argc != 4) || (which == rthash && args.argc != 3)) {
00292       ast_log(LOG_WARNING, "Syntax: %s(family,fieldmatch,value%s) - missing argument!\n", cmd, which == rtfield ? ",fieldname" : "");
00293       return -1;
00294    }
00295 
00296    if (chan) {
00297       ast_autoservice_start(chan);
00298    }
00299 
00300    if (!(head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL))) {
00301       if (chan) {
00302          ast_autoservice_stop(chan);
00303       }
00304       return -1;
00305    }
00306 
00307    ast_str_reset(fields);
00308    ast_str_reset(values);
00309 
00310    for (var = head; var; var = var->next) {
00311       if (which == rtfield) {
00312          ast_debug(1, "Comparing %s to %s\n", var->name, args.fieldname);
00313          if (!strcasecmp(var->name, args.fieldname)) {
00314             ast_debug(1, "Match! Value is %s\n", var->value);
00315             ast_copy_string(buf, var->value, len);
00316             break;
00317          }
00318       } else if (which == rthash) {
00319          ast_debug(1, "Setting hash key %s to value %s\n", var->name, var->value);
00320          ast_str_append(&fields, 0, "%s%s", first ? "" : ",", ast_str_set_escapecommas(&escapebuf, 0, var->name, INT_MAX));
00321          ast_str_append(&values, 0, "%s%s", first ? "" : ",", ast_str_set_escapecommas(&escapebuf, 0, var->value, INT_MAX));
00322          first = 0;
00323       }
00324    }
00325    ast_variables_destroy(head);
00326 
00327    if (which == rthash) {
00328       pbx_builtin_setvar_helper(chan, "~ODBCFIELDS~", ast_str_buffer(fields));
00329       ast_copy_string(buf, ast_str_buffer(values), len);
00330    }
00331 
00332    if (chan) {
00333       ast_autoservice_stop(chan);
00334    }
00335 
00336    return 0;
00337 }
00338 
00339 static int function_realtime_store(struct ast_channel *chan, const char *cmd, char *data, const char *value)
00340 {
00341    int res = 0;
00342    char storeid[32];
00343    char *valcopy;
00344    AST_DECLARE_APP_ARGS(a,
00345       AST_APP_ARG(family);
00346       AST_APP_ARG(f)[30]; /* fields */
00347    );
00348 
00349    AST_DECLARE_APP_ARGS(v,
00350       AST_APP_ARG(v)[30]; /* values */
00351    );
00352 
00353    if (ast_strlen_zero(data)) {
00354       ast_log(LOG_WARNING, "Syntax: REALTIME_STORE(family,field1,field2,...,field30) - missing argument!\n");
00355       return -1;
00356    }
00357 
00358    if (chan)
00359       ast_autoservice_start(chan);
00360 
00361    valcopy = ast_strdupa(value);
00362    AST_STANDARD_APP_ARGS(a, data);
00363    AST_STANDARD_APP_ARGS(v, valcopy);
00364 
00365    res = ast_store_realtime(a.family, 
00366       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],
00367       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],
00368       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],
00369       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],
00370       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],
00371       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
00372    );
00373 
00374    if (res < 0) {
00375       ast_log(LOG_WARNING, "Failed to store. Check the debug log for possible data repository related entries.\n");
00376    } else {
00377       snprintf(storeid, sizeof(storeid), "%d", res);
00378       pbx_builtin_setvar_helper(chan, "RTSTOREID", storeid);
00379    }
00380 
00381    if (chan)
00382       ast_autoservice_stop(chan);
00383 
00384    return 0;
00385 }
00386 
00387 static int function_realtime_readdestroy(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len) 
00388 {
00389    struct ast_variable *var, *head;
00390    struct ast_str *out;
00391    size_t resultslen;
00392    int n;
00393    AST_DECLARE_APP_ARGS(args,
00394       AST_APP_ARG(family);
00395       AST_APP_ARG(fieldmatch);
00396       AST_APP_ARG(value);
00397       AST_APP_ARG(delim1);
00398       AST_APP_ARG(delim2);
00399    );
00400 
00401    if (ast_strlen_zero(data)) {
00402       ast_log(LOG_WARNING, "Syntax: REALTIME_DESTROY(family,fieldmatch[,value[,delim1[,delim2]]]) - missing argument!\n");
00403       return -1;
00404    }
00405 
00406    AST_STANDARD_APP_ARGS(args, data);
00407 
00408    if (!args.delim1)
00409       args.delim1 = ",";
00410    if (!args.delim2)
00411       args.delim2 = "=";
00412 
00413    if (chan)
00414       ast_autoservice_start(chan);
00415 
00416    head = ast_load_realtime_all(args.family, args.fieldmatch, args.value, SENTINEL);
00417 
00418    if (!head) {
00419       if (chan)
00420          ast_autoservice_stop(chan);
00421       return -1;
00422    }
00423 
00424    resultslen = 0;
00425    n = 0;
00426    for (var = head; var; n++, var = var->next)
00427       resultslen += strlen(var->name) + strlen(var->value);
00428    /* add space for delimiters and final '\0' */
00429    resultslen += n * (strlen(args.delim1) + strlen(args.delim2)) + 1;
00430 
00431    out = ast_str_alloca(resultslen);
00432    for (var = head; var; var = var->next) {
00433       ast_str_append(&out, 0, "%s%s%s%s", var->name, args.delim2, var->value, args.delim1);
00434    }
00435    ast_copy_string(buf, ast_str_buffer(out), len);
00436 
00437    ast_destroy_realtime(args.family, args.fieldmatch, args.value, SENTINEL);
00438    ast_variables_destroy(head);
00439 
00440    if (chan)
00441       ast_autoservice_stop(chan);
00442 
00443    return 0;
00444 }
00445 
00446 static struct ast_custom_function realtime_function = {
00447    .name = "REALTIME",
00448    .read = function_realtime_read,
00449    .write = function_realtime_write,
00450 };
00451 
00452 static struct ast_custom_function realtimefield_function = {
00453    .name = "REALTIME_FIELD",
00454    .read = realtimefield_read,
00455    .write = function_realtime_write,
00456 };
00457 
00458 static struct ast_custom_function realtimehash_function = {
00459    .name = "REALTIME_HASH",
00460    .read = realtimefield_read,
00461 };
00462 
00463 static struct ast_custom_function realtime_store_function = {
00464    .name = "REALTIME_STORE",
00465    .write = function_realtime_store,
00466 };
00467 
00468 static struct ast_custom_function realtime_destroy_function = {
00469    .name = "REALTIME_DESTROY",
00470    .read = function_realtime_readdestroy,
00471 };
00472 
00473 static int unload_module(void)
00474 {
00475    int res = 0;
00476    res |= ast_custom_function_unregister(&realtime_function);
00477    res |= ast_custom_function_unregister(&realtime_store_function);
00478    res |= ast_custom_function_unregister(&realtime_destroy_function);
00479    res |= ast_custom_function_unregister(&realtimefield_function);
00480    res |= ast_custom_function_unregister(&realtimehash_function);
00481    return res;
00482 }
00483 
00484 static int load_module(void)
00485 {
00486    int res = 0;
00487    res |= ast_custom_function_register(&realtime_function);
00488    res |= ast_custom_function_register(&realtime_store_function);
00489    res |= ast_custom_function_register(&realtime_destroy_function);
00490    res |= ast_custom_function_register(&realtimefield_function);
00491    res |= ast_custom_function_register(&realtimehash_function);
00492    return res;
00493 }
00494 
00495 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Read/Write/Store/Destroy values from a RealTime repository");

Generated on Mon Jun 27 16:50:54 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7