Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:11 2009

## Asterisk developer's documentation

# app_read.c File Reference

Trivial application to read a variable. More...

`#include <stdlib.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include "asterisk.h"`
`#include "asterisk/lock.h"`
`#include "asterisk/file.h"`
`#include "asterisk/logger.h"`
`#include "asterisk/channel.h"`
`#include "asterisk/pbx.h"`
`#include "asterisk/app.h"`
`#include "asterisk/module.h"`
`#include "asterisk/translate.h"`
`#include "asterisk/options.h"`
`#include "asterisk/utils.h"`

Include dependency graph for app_read.c:

Go to the source code of this file.

## Defines

#define | ast_next_data(instr, ptr, delim) if((ptr=strchr(instr,delim))) { *(ptr) = '\0' ; ptr++;}

## Functions

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 | read_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 = "Read"
static char * | descrip
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static char * | synopsis = "Read a variable"
static char * | tdesc = "Read Variable Application"

## Detailed Description

Trivial application to read a variable.

Definition in file app_read.c.

## Define Documentation

#define ast_next_data | ( | instr,
|  | ptr,
|  | delim |  | ) | if((ptr=strchr(instr,delim))) { *(ptr) = '\0' ; ptr++;}

Definition at line 72 of file app_read.c.

## Function Documentation

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 220 of file app_read.c.

    00221 {
    00222    return tdesc;
    00223 }

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 232 of file app_read.c.

References ASTERISK_GPL_KEY.

    00233 {
    00234    return ASTERISK_GPL_KEY;
    00235 }

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 215 of file app_read.c.

References ast_register_application(), and read_exec().

    00216 {
    00217    return ast_register_application(app, read_exec, synopsis, descrip);
    00218 }

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

Definition at line 74 of file app_read.c.

References ast_channel::_state, ast_answer(), ast_app_getdata(), ast_app_separate_args(), ast_log(), AST_STATE_UP, ast_stopstream(), ast_strdupa, ast_strlen_zero(), ast_verbose(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, LOG_WARNING, option_verbose, pbx_builtin_setvar_helper(), and VERBOSE_PREFIX_3.

Referenced by load_module().

    00075 {
    00076    int res = 0;
    00077    struct localuser *u;
    00078    char tmp[256];
    00079    char *timeout = NULL;
    00080    char *varname = NULL;
    00081    char *filename = NULL;
    00082    char *loops;
    00083    char *maxdigitstr=NULL;
    00084    char *options=NULL;
    00085    int option_skip = 0;
    00086    int option_noanswer = 0;
    00087    int maxdigits=255;
    00088    int tries = 1;
    00089    int to = 0;
    00090    int x = 0;
    00091    char *argcopy = NULL;
    00092    char *args[8];
    00093
    00094    if (ast_strlen_zero(data)) {
    00095       ast_log(LOG_WARNING, "Read requires an argument (variable)\n");
    00096       return -1;
    00097    }
    00098
    00099    LOCAL_USER_ADD(u);
    00100
    00101    argcopy = ast_strdupa(data);
    00102    if (!argcopy) {
    00103       ast_log(LOG_ERROR, "Out of memory\n");
    00104       LOCAL_USER_REMOVE(u);
    00105       return -1;
    00106    }
    00107
    00108    if (ast_app_separate_args(argcopy, '|', args, sizeof(args) / sizeof(args[0])) < 1) {
    00109       ast_log(LOG_WARNING, "Cannot Parse Arguments.\n");
    00110       LOCAL_USER_REMOVE(u);
    00111       return -1;
    00112    }
    00113
    00114    varname = args[x++];
    00115    filename = args[x++];
    00116    maxdigitstr = args[x++];
    00117    options = args[x++];
    00118    loops = args[x++];
    00119    timeout = args[x++];
    00120
    00121    if (options) {
    00122       if (!strcasecmp(options, "skip"))
    00123          option_skip = 1;
    00124       else if (!strcasecmp(options, "noanswer"))
    00125          option_noanswer = 1;
    00126       else {
    00127          if (strchr(options, 's'))
    00128             option_skip = 1;
    00129          if (strchr(options, 'n'))
    00130             option_noanswer = 1;
    00131       }
    00132    }
    00133
    00134    if(loops) {
    00135       tries = atoi(loops);
    00136       if(tries <= 0)
    00137          tries = 1;
    00138    }
    00139
    00140    if(timeout) {
    00141       to = atoi(timeout);
    00142       if (to <= 0)
    00143          to = 0;
    00144       else
    00145          to *= 1000;
    00146    }
    00147
    00148    if (ast_strlen_zero(filename))
    00149       filename = NULL;
    00150    if (maxdigitstr) {
    00151       maxdigits = atoi(maxdigitstr);
    00152       if ((maxdigits<1) || (maxdigits>255)) {
    00153             maxdigits = 255;
    00154       } else if (option_verbose > 2)
    00155          ast_verbose(VERBOSE_PREFIX_3 "Accepting a maximum of %d digits.\n", maxdigits);
    00156    }
    00157    if (ast_strlen_zero(varname)) {
    00158       ast_log(LOG_WARNING, "Invalid! Usage: Read(variable[|filename][|maxdigits][|option][|attempts][|timeout])\n\n");
    00159       LOCAL_USER_REMOVE(u);
    00160       return -1;
    00161    }
    00162
    00163    if (chan->_state != AST_STATE_UP) {
    00164       if (option_skip) {
    00165          /* At the user's option, skip if the line is not up */
    00166          pbx_builtin_setvar_helper(chan, varname, "\0");
    00167          LOCAL_USER_REMOVE(u);
    00168          return 0;
    00169       } else if (!option_noanswer) {
    00170          /* Otherwise answer unless we're supposed to read while on-hook */
    00171          res = ast_answer(chan);
    00172       }
    00173    }
    00174    if (!res) {
    00175       while(tries && !res) {
    00176          ast_stopstream(chan);
    00177          res = ast_app_getdata(chan, filename, tmp, maxdigits, to);
    00178          if (res > -1) {
    00179             pbx_builtin_setvar_helper(chan, varname, tmp);
    00180             if (!ast_strlen_zero(tmp)) {
    00181                if (option_verbose > 2)
    00182                   ast_verbose(VERBOSE_PREFIX_3 "User entered '%s'\n", tmp);
    00183                tries = 0;
    00184             } else {
    00185                tries--;
    00186                if (option_verbose > 2) {
    00187                   if (tries)
    00188                      ast_verbose(VERBOSE_PREFIX_3 "User entered nothing, %d chance%s left\n", tries, (tries != 1) ? "s" : "");
    00189                   else
    00190                      ast_verbose(VERBOSE_PREFIX_3 "User entered nothing.\n");
    00191                }
    00192             }
    00193             res = 0;
    00194          } else {
    00195             if (option_verbose > 2)
    00196                ast_verbose(VERBOSE_PREFIX_3 "User disconnected\n");
    00197          }
    00198       }
    00199    }
    00200    LOCAL_USER_REMOVE(u);
    00201    return res;
    00202 }

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 204 of file app_read.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00205 {
    00206    int res;
    00207
    00208    res = ast_unregister_application(app);
    00209
    00210    STANDARD_HANGUP_LOCALUSERS;
    00211
    00212    return res;
    00213 }

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 225 of file app_read.c.

References STANDARD_USECOUNT.

    00226 {
    00227    int res;
    00228    STANDARD_USECOUNT(res);
    00229    return res;
    00230 }

## Variable Documentation

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

Definition at line 47 of file app_read.c.

char* descrip`[static]`

Definition at line 51 of file app_read.c.

LOCAL_USER_DECL

Definition at line 70 of file app_read.c.

STANDARD_LOCAL_USER

Definition at line 68 of file app_read.c.

char* synopsis = "Read a variable"`[static]`

Definition at line 49 of file app_read.c.

char* tdesc = "Read Variable Application"`[static]`

Definition at line 45 of file app_read.c.