Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:01 2009

## Asterisk developer's documentation

# app_db.c File Reference

Database access functions. More...

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

Include dependency graph for app_db.c:

Go to the source code of this file.

## Functions

static int | del_exec (struct ast_channel *chan, void *data)
static int | deltree_exec (struct ast_channel *chan, void *data)
char * | description (void)
| Provides a description of the module.
static int | get_exec (struct ast_channel *chan, void *data)
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
static int | put_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 * | d_app = "DBdel"
static char * | d_descrip
static char * | d_synopsis = "Delete a key from the database"
static char * | dt_app = "DBdeltree"
static char * | dt_descrip
static char * | dt_synopsis = "Delete a family or keytree from the database"
static char * | g_app = "DBget"
static char * | g_descrip
static char * | g_synopsis = "Retrieve a value from the database"
| LOCAL_USER_DECL
static char * | p_app = "DBput"
static char * | p_descrip
static char * | p_synopsis = "Store a value in the database"
| STANDARD_LOCAL_USER
static char * | tdesc = "Database Access Functions"

## Detailed Description

Database access functions.

Definition in file app_db.c.

## Function Documentation

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

Definition at line 133 of file app_db.c.

References ast_db_del(), ast_log(), ast_strdupa, ast_verbose(), key(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_DEBUG, LOG_ERROR, option_verbose, strsep(), and VERBOSE_PREFIX_3.

Referenced by load_module().

    00134 {
    00135    char *argv, *family, *key;
    00136    struct localuser *u;
    00137
    00138    LOCAL_USER_ADD(u);
    00139
    00140    argv = ast_strdupa(data);
    00141    if (!argv) {
    00142       ast_log (LOG_ERROR, "Memory allocation failed\n");
    00143       LOCAL_USER_REMOVE(u);
    00144       return 0;
    00145    }
    00146
    00147    if (strchr(argv, '/')) {
    00148       family = strsep(&argv, "/");
    00149       key = strsep(&argv, "\0");
    00150       if (!family || !key) {
    00151          ast_log(LOG_DEBUG, "Ignoring; Syntax error in argument\n");
    00152          LOCAL_USER_REMOVE(u);
    00153          return 0;
    00154       }
    00155       if (option_verbose > 2)
    00156          ast_verbose(VERBOSE_PREFIX_3 "DBdel: family=%s, key=%s\n", family, key);
    00157       if (ast_db_del(family, key)) {
    00158          if (option_verbose > 2)
    00159             ast_verbose(VERBOSE_PREFIX_3 "DBdel: Error deleting key from database.\n");
    00160       }
    00161    } else {
    00162       ast_log(LOG_DEBUG, "Ignoring, no parameters\n");
    00163    }
    00164
    00165    LOCAL_USER_REMOVE(u);
    00166
    00167    return 0;
    00168 }

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

Definition at line 87 of file app_db.c.

References ast_db_deltree(), ast_log(), ast_strdupa, ast_strlen_zero(), ast_verbose(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_DEBUG, LOG_ERROR, option_verbose, strsep(), and VERBOSE_PREFIX_3.

Referenced by load_module().

    00088 {
    00089    char *argv, *family, *keytree;
    00090    struct localuser *u;
    00091
    00092    LOCAL_USER_ADD(u);
    00093
    00094    argv = ast_strdupa(data);
    00095    if (!argv) {
    00096       ast_log(LOG_ERROR, "Memory allocation failed\n");
    00097       LOCAL_USER_REMOVE(u);
    00098       return 0;
    00099    }
    00100
    00101    if (strchr(argv, '/')) {
    00102       family = strsep(&argv, "/");
    00103       keytree = strsep(&argv, "\0");
    00104          if (!family || !keytree) {
    00105             ast_log(LOG_DEBUG, "Ignoring; Syntax error in argument\n");
    00106             LOCAL_USER_REMOVE(u);
    00107             return 0;
    00108          }
    00109       if (ast_strlen_zero(keytree))
    00110          keytree = 0;
    00111    } else {
    00112       family = argv;
    00113       keytree = 0;
    00114    }
    00115
    00116    if (option_verbose > 2) {
    00117       if (keytree)
    00118          ast_verbose(VERBOSE_PREFIX_3 "DBdeltree: family=%s, keytree=%s\n", family, keytree);
    00119       else
    00120          ast_verbose(VERBOSE_PREFIX_3 "DBdeltree: family=%s\n", family);
    00121    }
    00122
    00123    if (ast_db_deltree(family, keytree)) {
    00124       if (option_verbose > 2)
    00125          ast_verbose(VERBOSE_PREFIX_3 "DBdeltree: Error deleting key from database.\n");
    00126    }
    00127
    00128    LOCAL_USER_REMOVE(u);
    00129
    00130    return 0;
    00131 }

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 308 of file app_db.c.

    00309 {
    00310    return tdesc;
    00311 }

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

Definition at line 215 of file app_db.c.

References ast_db_get(), ast_goto_if_exists(), ast_log(), ast_strdupa, ast_verbose(), ast_channel::context, dep_warning, ast_channel::exten, key(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_DEBUG, LOG_ERROR, LOG_WARNING, option_priority_jumping, option_verbose, pbx_builtin_setvar_helper(), ast_channel::priority, strsep(), and VERBOSE_PREFIX_3.

Referenced by load_module().

    00216 {
    00217    char *argv, *varname, *family, *key, *options = NULL;
    00218    char dbresult[256];
    00219    static int dep_warning = 0;
    00220    int priority_jump = 0;
    00221    struct localuser *u;
    00222
    00223    LOCAL_USER_ADD(u);
    00224
    00225    if (!dep_warning) {
    00226       ast_log(LOG_WARNING, "This application has been deprecated, please use the ${DB(family/key)} function instead.\n");
    00227       dep_warning = 1;
    00228    }
    00229
    00230    argv = ast_strdupa(data);
    00231    if (!argv) {
    00232       ast_log(LOG_ERROR, "Memory allocation failed\n");
    00233       LOCAL_USER_REMOVE(u);
    00234       return 0;
    00235    }
    00236
    00237    if (strchr(argv, '=') && strchr(argv, '/')) {
    00238       varname = strsep(&argv, "=");
    00239       family = strsep(&argv, "/");
    00240       if (strchr((void *)&argv, '|')) {
    00241          key = strsep(&argv, "|");
    00242          options = strsep(&argv, "\0");
    00243       } else
    00244          key = strsep(&argv, "\0");
    00245
    00246       if (!varname || !family || !key) {
    00247          ast_log(LOG_DEBUG, "Ignoring; Syntax error in argument\n");
    00248          LOCAL_USER_REMOVE(u);
    00249          return 0;
    00250       }
    00251
    00252       if (options) {
    00253          if (strchr(options, 'j'))
    00254             priority_jump = 1;
    00255       }
    00256
    00257       if (option_verbose > 2)
    00258          ast_verbose(VERBOSE_PREFIX_3 "DBget: varname=%s, family=%s, key=%s\n", varname, family, key);
    00259       if (!ast_db_get(family, key, dbresult, sizeof (dbresult) - 1)) {
    00260          pbx_builtin_setvar_helper(chan, varname, dbresult);
    00261          if (option_verbose > 2)
    00262             ast_verbose(VERBOSE_PREFIX_3 "DBget: set variable %s to %s\n", varname, dbresult);
    00263          pbx_builtin_setvar_helper(chan, "DBGETSTATUS", "FOUND");
    00264       } else {
    00265          if (option_verbose > 2)
    00266          ast_verbose(VERBOSE_PREFIX_3 "DBget: Value not found in database.\n");
    00267          if (priority_jump || option_priority_jumping) {
    00268             /* Send the call to n+101 priority, where n is the current priority */
    00269             ast_goto_if_exists(chan, chan->context, chan->exten, chan->priority + 101);
    00270          }
    00271          pbx_builtin_setvar_helper(chan, "DBGETSTATUS", "NOTFOUND");
    00272       }
    00273    } else {
    00274       ast_log(LOG_DEBUG, "Ignoring, no parameters\n");
    00275    }
    00276
    00277    LOCAL_USER_REMOVE(u);
    00278
    00279    return 0;
    00280 }

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 320 of file app_db.c.

References ASTERISK_GPL_KEY.

    00321 {
    00322    return ASTERISK_GPL_KEY;
    00323 }

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 296 of file app_db.c.

References ast_register_application(), del_exec(), deltree_exec(), get_exec(), and put_exec().

    00297 {
    00298    int retval;
    00299
    00300    retval = ast_register_application(g_app, get_exec, g_synopsis, g_descrip);
    00301    retval |= ast_register_application(p_app, put_exec, p_synopsis, p_descrip);
    00302    retval |= ast_register_application(d_app, del_exec, d_synopsis, d_descrip);
    00303    retval |= ast_register_application(dt_app, deltree_exec, dt_synopsis, dt_descrip);
    00304
    00305    return retval;
    00306 }

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

Definition at line 170 of file app_db.c.

References ast_db_put(), ast_log(), ast_strdupa, ast_verbose(), dep_warning, key(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_DEBUG, LOG_ERROR, LOG_WARNING, option_verbose, strsep(), and VERBOSE_PREFIX_3.

Referenced by load_module().

    00171 {
    00172    char *argv, *value, *family, *key;
    00173    static int dep_warning = 0;
    00174    struct localuser *u;
    00175
    00176    LOCAL_USER_ADD(u);
    00177
    00178    if (!dep_warning) {
    00179       ast_log(LOG_WARNING, "This application has been deprecated, please use the ${DB(family/key)} function instead.\n");
    00180       dep_warning = 1;
    00181    }
    00182
    00183    argv = ast_strdupa(data);
    00184    if (!argv) {
    00185       ast_log(LOG_ERROR, "Memory allocation failed\n");
    00186       LOCAL_USER_REMOVE(u);
    00187       return 0;
    00188    }
    00189
    00190    if (strchr(argv, '/') && strchr(argv, '=')) {
    00191       family = strsep(&argv, "/");
    00192       key = strsep(&argv, "=");
    00193       value = strsep(&argv, "\0");
    00194       if (!value || !family || !key) {
    00195          ast_log(LOG_DEBUG, "Ignoring; Syntax error in argument\n");
    00196          LOCAL_USER_REMOVE(u);
    00197          return 0;
    00198       }
    00199       if (option_verbose > 2)
    00200          ast_verbose(VERBOSE_PREFIX_3 "DBput: family=%s, key=%s, value=%s\n", family, key, value);
    00201       if (ast_db_put(family, key, value)) {
    00202          if (option_verbose > 2)
    00203             ast_verbose(VERBOSE_PREFIX_3 "DBput: Error writing value to database.\n");
    00204       }
    00205
    00206    } else   {
    00207       ast_log (LOG_DEBUG, "Ignoring, no parameters\n");
    00208    }
    00209
    00210    LOCAL_USER_REMOVE(u);
    00211
    00212    return 0;
    00213 }

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 282 of file app_db.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00283 {
    00284    int retval;
    00285
    00286    retval = ast_unregister_application(dt_app);
    00287    retval |= ast_unregister_application(d_app);
    00288    retval |= ast_unregister_application(p_app);
    00289    retval |= ast_unregister_application(g_app);
    00290
    00291    STANDARD_HANGUP_LOCALUSERS;
    00292
    00293    return retval;
    00294 }

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 313 of file app_db.c.

References STANDARD_USECOUNT.

    00314 {
    00315    int res;
    00316    STANDARD_USECOUNT(res);
    00317    return res;
    00318 }

## Variable Documentation

char* d_app = "DBdel"`[static]`

Definition at line 75 of file app_db.c.

char* d_descrip`[static]`

Initial value:

    "  DBdel(family/key): This application will delete a key from the Asterisk\n"
    "database.\n"

Definition at line 65 of file app_db.c.

char* d_synopsis = "Delete a key from the database"`[static]`

Definition at line 80 of file app_db.c.

char* dt_app = "DBdeltree"`[static]`

Definition at line 76 of file app_db.c.

char* dt_descrip`[static]`

Initial value:

    "  DBdeltree(family[/keytree]): This application will delete a family or keytree\n"
    "from the Asterisk database\n"

Definition at line 69 of file app_db.c.

char* dt_synopsis = "Delete a family or keytree from the database"`[static]`

Definition at line 81 of file app_db.c.

char* g_app = "DBget"`[static]`

Definition at line 73 of file app_db.c.

char* g_descrip`[static]`

Definition at line 50 of file app_db.c.

char* g_synopsis = "Retrieve a value from the database"`[static]`

Definition at line 78 of file app_db.c.

LOCAL_USER_DECL

Definition at line 85 of file app_db.c.

char* p_app = "DBput"`[static]`

Definition at line 74 of file app_db.c.

char* p_descrip`[static]`

Initial value:

    "  DBput(family/key=value): This application will store the given value in the\n"
    "specified location in the Asterisk database.\n"
    "  This application has been deprecated in favor of the DB function.\n"

Definition at line 60 of file app_db.c.

char* p_synopsis = "Store a value in the database"`[static]`

Definition at line 79 of file app_db.c.

STANDARD_LOCAL_USER

Definition at line 83 of file app_db.c.

char* tdesc = "Database Access Functions"`[static]`

Definition at line 48 of file app_db.c.