Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:12 2009

## Asterisk developer's documentation

# app_realtime.c File Reference

RealTime App. More...

`#include <stdlib.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include <unistd.h>`
`#include "asterisk.h"`
`#include "asterisk/file.h"`
`#include "asterisk/logger.h"`
`#include "asterisk/channel.h"`
`#include "asterisk/options.h"`
`#include "asterisk/pbx.h"`
`#include "asterisk/config.h"`
`#include "asterisk/module.h"`
`#include "asterisk/lock.h"`
`#include "asterisk/cli.h"`

Include dependency graph for app_realtime.c:

Go to the source code of this file.

## Defines

#define | crop_data(str) { *(str) = '\0' ; (str)++; }
#define | next_one(var) var = var->next

## Functions

static int | cli_load_realtime (int fd, int argc, char **argv)
static int | cli_update_realtime (int fd, int argc, char **argv)
char * | description (void)
| Provides a description of the module.
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
static int | realtime_exec (struct ast_channel *chan, void *data)
static int | realtime_update_exec (struct ast_channel *chan, void *data)
int | unload_module (void)
| Cleanup all module structures, sockets, etc.
int | usecount (void)
| Provides a usecount.

## Variables

static char * | app = "RealTime"
static struct ast_cli_entry | cli_load_realtime_cmd
static char | cli_load_realtime_usage []
static struct ast_cli_entry | cli_update_realtime_cmd
static char | cli_update_realtime_usage []
static char * | desc
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static char * | synopsis = "Realtime Data Lookup"
static char * | tdesc = "Realtime Data Lookup/Rewrite"
static char * | uapp = "RealTimeUpdate"
static char * | udesc
static char * | USAGE = "RealTime(<family>|<colmatch>|<value>[|<prefix>])"
static char * | usynopsis = "Realtime Data Rewrite"
static char * | UUSAGE = "RealTimeUpdate(<family>|<colmatch>|<value>|<newcol>|<newval>)"

## Detailed Description

RealTime App.

Definition in file app_realtime.c.

## Define Documentation

#define crop_data | ( | str |  | ) | { *(str) = '\0' ; (str)++; }

Definition at line 47 of file app_realtime.c.

Referenced by realtime_exec(), and realtime_update_exec().

#define next_one | ( | var |  | ) | var = var->next

Definition at line 46 of file app_realtime.c.

## Function Documentation

static int cli_load_realtime | ( | int | fd,
|  | int | argc,
|  | char ** | argv |
| ) |  |  | `[static]`

Definition at line 67 of file app_realtime.c.

References ast_cli(), ast_load_realtime(), ast_variable::name, ast_variable::next, RESULT_FAILURE, RESULT_SUCCESS, ast_variable::value, and var.

    00068 {
    00069    char *header_format = "%30s  %-30s\n";
    00070    struct ast_variable *var=NULL;
    00071
    00072    if(argc<5) {
    00073       ast_cli(fd, "You must supply a family name, a column to match on, and a value to match to.\n");
    00074       return RESULT_FAILURE;
    00075    }
    00076
    00077    var = ast_load_realtime(argv[2], argv[3], argv[4], NULL);
    00078
    00079    if(var) {
    00080       ast_cli(fd, header_format, "Column Name", "Column Value");
    00081       ast_cli(fd, header_format, "--------------------", "--------------------");
    00082       while(var) {
    00083          ast_cli(fd, header_format, var->name, var->value);
    00084          var = var->next;
    00085       }
    00086    } else {
    00087       ast_cli(fd, "No rows found matching search criteria.\n");
    00088    }
    00089    return RESULT_SUCCESS;
    00090 }

static int cli_update_realtime | ( | int | fd,
|  | int | argc,
|  | char ** | argv |
| ) |  |  | `[static]`

Definition at line 92 of file app_realtime.c.

References ast_cli(), ast_update_realtime(), RESULT_FAILURE, and RESULT_SUCCESS.

    00092                                                               {
    00093    int res = 0;
    00094
    00095    if(argc<7) {
    00096       ast_cli(fd, "You must supply a family name, a column to update on, a new value, column to match, and value to to match.\n");
    00097       ast_cli(fd, "Ex: realtime update sipfriends name bobsphone port 4343\n will execute SQL as UPDATE sipfriends SET port = 4343 WHERE name = bobsphone\n");
    00098       return RESULT_FAILURE;
    00099    }
    00100
    00101    res = ast_update_realtime(argv[2], argv[3], argv[4], argv[5], argv[6], NULL);
    00102
    00103    if(res < 0) {
    00104       ast_cli(fd, "Failed to update. Check the debug log for possible SQL related entries.\n");
    00105       return RESULT_SUCCESS;
    00106    }
    00107
    00108        ast_cli(fd, "Updated %d RealTime record%s.\n", res, (res != 1) ? "s" : "");
    00109
    00110    return RESULT_SUCCESS;
    00111 }

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 246 of file app_realtime.c.

    00247 {
    00248    return tdesc;
    00249 }

char* key | ( | void |  | ) |

Returns the ASTERISK_GPL_KEY.

This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does not return the EXACT message:

     char *key(void) {
             return ASTERISK_GPL_KEY;
     }

Returns:
  ASTERISK_GPL_KEY

Definition at line 258 of file app_realtime.c.

References ASTERISK_GPL_KEY.

    00259 {
    00260    return ASTERISK_GPL_KEY;
    00261 }

int load_module | ( | void |  | ) |

Initialize the module.

This function is called at module load time. Put all code in here that needs to set up your module's hardware, software, registrations, etc.

Returns:
  This function should return 0 on success and non-zero on failure. If the module is not loaded successfully, Asterisk will call its unload_module() function.

Initialize the Agents module. This function is being called by Asterisk when loading the module. Among other thing it registers applications, cli commands and reads the cofiguration file.

Returns:
  int Always 0.

TE STUFF END

Definition at line 234 of file app_realtime.c.

References ast_cli_register(), ast_register_application(), realtime_exec(), and realtime_update_exec().

    00235 {
    00236    int res;
    00237
    00238    res = ast_cli_register(&cli_load_realtime_cmd);
    00239    res |= ast_cli_register(&cli_update_realtime_cmd);
    00240    res |= ast_register_application(uapp, realtime_update_exec, usynopsis, udesc);
    00241    res |= ast_register_application(app, realtime_exec, synopsis, desc);
    00242
    00243    return res;
    00244 }

static int realtime_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 168 of file app_realtime.c.

References ast_load_realtime(), ast_log(), ast_strdupa, ast_strlen_zero(), ast_variables_destroy(), ast_verbose(), crop_data, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, ast_variable::name, ast_variable::next, option_verbose, pbx_builtin_setvar_helper(), ast_variable::value, var, and VERBOSE_PREFIX_4.

Referenced by load_module().

    00169 {
    00170    int res=0;
    00171    struct localuser *u;
    00172    struct ast_variable *var, *itt;
    00173    char *family=NULL, *colmatch=NULL, *value=NULL, *prefix=NULL, *vname=NULL;
    00174    size_t len;
    00175
    00176    if (ast_strlen_zero(data)) {
    00177       ast_log(LOG_ERROR,"Invalid input: usage %s\n",USAGE);
    00178       return -1;
    00179    }
    00180
    00181    LOCAL_USER_ADD(u);
    00182
    00183    if ((family = ast_strdupa(data))) {
    00184       if ((colmatch = strchr(family,'|'))) {
    00185          crop_data(colmatch);
    00186          if ((value = strchr(colmatch,'|'))) {
    00187             crop_data(value);
    00188             if ((prefix = strchr(value,'|')))
    00189                crop_data(prefix);
    00190          }
    00191       }
    00192    }
    00193    if (! (family && value && colmatch) ) {
    00194       ast_log(LOG_ERROR,"Invalid input: usage %s\n",USAGE);
    00195       res = -1;
    00196    } else {
    00197       if (option_verbose > 3)
    00198          ast_verbose(VERBOSE_PREFIX_4"Realtime Lookup: family:'%s' colmatch:'%s' value:'%s'\n",family,colmatch,value);
    00199       if ((var = ast_load_realtime(family, colmatch, value, NULL))) {
    00200          for (itt = var; itt; itt = itt->next) {
    00201             if(prefix) {
    00202                len = strlen(prefix) + strlen(itt->name) + 2;
    00203                vname = alloca(len);
    00204                snprintf(vname,len,"%s%s",prefix,itt->name);
    00205
    00206             } else
    00207                vname = itt->name;
    00208
    00209             pbx_builtin_setvar_helper(chan, vname, itt->value);
    00210          }
    00211          ast_variables_destroy(var);
    00212       } else if (option_verbose > 3)
    00213          ast_verbose(VERBOSE_PREFIX_4"No Realtime Matches Found.\n");
    00214    }
    00215
    00216    LOCAL_USER_REMOVE(u);
    00217    return res;
    00218 }

static int realtime_update_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 129 of file app_realtime.c.

References ast_log(), ast_strdupa, ast_strlen_zero(), ast_update_realtime(), crop_data, LOCAL_USER_ADD, LOCAL_USER_REMOVE, and LOG_ERROR.

Referenced by load_module().

    00130 {
    00131    char *family=NULL, *colmatch=NULL, *value=NULL, *newcol=NULL, *newval=NULL;
    00132    struct localuser *u;
    00133    int res = 0;
    00134
    00135    if (ast_strlen_zero(data)) {
    00136       ast_log(LOG_ERROR,"Invalid input: usage %s\n",UUSAGE);
    00137       return -1;
    00138    }
    00139
    00140    LOCAL_USER_ADD(u);
    00141
    00142    if ((family = ast_strdupa(data))) {
    00143       if ((colmatch = strchr(family,'|'))) {
    00144          crop_data(colmatch);
    00145          if ((value = strchr(colmatch,'|'))) {
    00146             crop_data(value);
    00147             if ((newcol = strchr(value,'|'))) {
    00148                crop_data(newcol);
    00149                if ((newval = strchr(newcol,'|')))
    00150                   crop_data(newval);
    00151             }
    00152          }
    00153       }
    00154    }
    00155    if (! (family && value && colmatch && newcol && newval) ) {
    00156       ast_log(LOG_ERROR,"Invalid input: usage %s\n",UUSAGE);
    00157       res = -1;
    00158    } else {
    00159       ast_update_realtime(family,colmatch,value,newcol,newval,NULL);
    00160    }
    00161
    00162    LOCAL_USER_REMOVE(u);
    00163
    00164    return res;
    00165 }

int unload_module | ( | void |  | ) |

Cleanup all module structures, sockets, etc.

This is called at exit. Any registrations and memory allocations need to be unregistered and free'd here. Nothing else will do these for you (until exit).

Returns:
  Zero on success, or non-zero on error.

Definition at line 220 of file app_realtime.c.

References ast_cli_unregister(), ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00221 {
    00222    int res;
    00223
    00224    res = ast_cli_unregister(&cli_load_realtime_cmd);
    00225    res |= ast_cli_unregister(&cli_update_realtime_cmd);
    00226    res |= ast_unregister_application(uapp);
    00227    res |= ast_unregister_application(app);
    00228
    00229    STANDARD_HANGUP_LOCALUSERS;
    00230
    00231    return res;
    00232 }

int usecount | ( | void |  | ) |

Provides a usecount.

This function will be called by various parts of asterisk. Basically, all it has to do is to return a usecount when called. You will need to maintain your usecount within the module somewhere. The usecount should be how many channels provided by this module are in use.

Returns:
  The module's usecount.

Definition at line 251 of file app_realtime.c.

References STANDARD_USECOUNT.

    00252 {
    00253    int res;
    00254    STANDARD_USECOUNT(res);
    00255    return res;
    00256 }

## Variable Documentation

char* app = "RealTime"`[static]`

Definition at line 50 of file app_realtime.c.

struct ast_cli_entry cli_load_realtime_cmd`[static]`

Initial value:

     {
            { "realtime", "load", NULL, NULL }, cli_load_realtime,
            "Used to print out RealTime variables.", cli_load_realtime_usage, NULL }

Definition at line 117 of file app_realtime.c.

char cli_load_realtime_usage[]`[static]`

Initial value:

    "Usage: realtime load <family> <colmatch> <value>\n"
    "       Prints out a list of variables using the RealTime driver.\n"

Definition at line 113 of file app_realtime.c.

struct ast_cli_entry cli_update_realtime_cmd`[static]`

Initial value:

     {
            { "realtime", "update", NULL, NULL }, cli_update_realtime,
            "Used to update RealTime variables.", cli_update_realtime_usage, NULL }

Definition at line 125 of file app_realtime.c.

char cli_update_realtime_usage[]`[static]`

Initial value:

    "Usage: realtime update <family> <colmatch> <value>\n"
    "       Update a single variable using the RealTime driver.\n"

Definition at line 121 of file app_realtime.c.

char* desc`[static]`

Initial value:

     "Use the RealTime config handler system to read data into channel variables.\n"
    "RealTime(<family>|<colmatch>|<value>[|<prefix>])\n\n"
    "All unique column names will be set as channel variables with optional prefix to the name.\n"
    "e.g. prefix of 'var_' would make the column 'name' become the variable ${var_name}\n\n"

Definition at line 56 of file app_realtime.c.

LOCAL_USER_DECL

Definition at line 65 of file app_realtime.c.

STANDARD_LOCAL_USER

Definition at line 64 of file app_realtime.c.

char* synopsis = "Realtime Data Lookup"`[static]`

Definition at line 52 of file app_realtime.c.

char* tdesc = "Realtime Data Lookup/Rewrite"`[static]`

Definition at line 49 of file app_realtime.c.

char* uapp = "RealTimeUpdate"`[static]`

Definition at line 51 of file app_realtime.c.

char* udesc`[static]`

Initial value:

     "Use the RealTime config handler system to update a value\n"
    "RealTimeUpdate(<family>|<colmatch>|<value>|<newcol>|<newval>)\n\n"
    "The column <newcol> in 'family' matching column <colmatch>=<value> will be updated to <newval>\n"

Definition at line 60 of file app_realtime.c.

char* USAGE = "RealTime(<family>|<colmatch>|<value>[|<prefix>])"`[static]`

Definition at line 54 of file app_realtime.c.

char* usynopsis = "Realtime Data Rewrite"`[static]`

Definition at line 53 of file app_realtime.c.

char* UUSAGE = "RealTimeUpdate(<family>|<colmatch>|<value>|<newcol>|<newval>)"`[static]`

Definition at line 55 of file app_realtime.c.