Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:16 2009

## Asterisk developer's documentation

# app_stack.c File Reference

Stack applications Gosub, Return, etc. More...

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

Include dependency graph for app_stack.c:

Go to the source code of this file.

## Defines

#define | STACKVAR "~GOSUB~STACK~"

## Functions

char * | description (void)
| Provides a description of the module.
static int | gosub_exec (struct ast_channel *chan, void *data)
static int | gosubif_exec (struct ast_channel *chan, void *data)
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
static int | pop_exec (struct ast_channel *chan, void *data)
static int | return_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 const char * | app_gosub = "Gosub"
static const char * | app_gosubif = "GosubIf"
static const char * | app_pop = "StackPop"
static const char * | app_return = "Return"
static const char * | gosub_descrip
static const char * | gosub_synopsis = "Jump to label, saving return address"
static const char * | gosubif_descrip
static const char * | gosubif_synopsis = "Jump to label, saving return address"
| LOCAL_USER_DECL
static const char * | pop_descrip
static const char * | pop_synopsis = "Remove one address from gosub stack"
static const char * | return_descrip
static const char * | return_synopsis = "Return from gosub routine"
| STANDARD_LOCAL_USER
static const char * | tdesc = "Stack Routines"

## Detailed Description

Stack applications Gosub, Return, etc.

Definition in file app_stack.c.

## Define Documentation

#define STACKVAR "~GOSUB~STACK~"

Definition at line 39 of file app_stack.c.

Referenced by gosub_exec(), pop_exec(), and return_exec().

## Function Documentation

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 176 of file app_stack.c.

References tdesc.

    00177 {
    00178    return (char *) tdesc;
    00179 }

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

Definition at line 95 of file app_stack.c.

References app_gosub, ast_log(), AST_MAX_EXTENSION, ast_parseable_goto(), ast_strlen_zero(), ast_channel::context, ast_channel::exten, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, pbx_builtin_pushvar_helper(), ast_channel::priority, and STACKVAR.

Referenced by gosubif_exec(), and load_module().

    00096 {
    00097    char newlabel[AST_MAX_EXTENSION * 2 + 3 + 11];
    00098    struct localuser *u;
    00099
    00100    if (ast_strlen_zero(data)) {
    00101       ast_log(LOG_ERROR, "%s requires an argument: %s([[context|]exten|]priority)\n", app_gosub, app_gosub);
    00102       return -1;
    00103    }
    00104
    00105    LOCAL_USER_ADD(u);
    00106    snprintf(newlabel, sizeof(newlabel), "%s|%s|%d", chan->context, chan->exten, chan->priority + 1);
    00107
    00108    if (ast_parseable_goto(chan, data)) {
    00109       LOCAL_USER_REMOVE(u);
    00110       return -1;
    00111    }
    00112
    00113    pbx_builtin_pushvar_helper(chan, STACKVAR, newlabel);
    00114    LOCAL_USER_REMOVE(u);
    00115
    00116    return 0;
    00117 }

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

Definition at line 119 of file app_stack.c.

References ast_log(), ast_strdupa, ast_strlen_zero(), gosub_exec(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, LOG_WARNING, pbx_checkcondition(), and strsep().

Referenced by load_module().

    00120 {
    00121    struct localuser *u;
    00122    char *condition="", *label1, *label2, *args;
    00123    int res=0;
    00124
    00125    if (ast_strlen_zero(data)) {
    00126       ast_log(LOG_WARNING, "GosubIf requires an argument\n");
    00127       return 0;
    00128    }
    00129
    00130    args = ast_strdupa((char *)data);
    00131    if (!args) {
    00132       ast_log(LOG_ERROR, "Out of memory\n");
    00133       return -1;
    00134    }
    00135
    00136    LOCAL_USER_ADD(u);
    00137
    00138    condition = strsep(&args, "?");
    00139    label1 = strsep(&args, ":");
    00140    label2 = args;
    00141
    00142    if (pbx_checkcondition(condition)) {
    00143       if (label1) {
    00144          res = gosub_exec(chan, label1);
    00145       }
    00146    } else if (label2) {
    00147       res = gosub_exec(chan, label2);
    00148    }
    00149
    00150    LOCAL_USER_REMOVE(u);
    00151    return res;
    00152 }

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 190 of file app_stack.c.

References ASTERISK_GPL_KEY.

    00191 {
    00192    return ASTERISK_GPL_KEY;
    00193 }

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 166 of file app_stack.c.

References app_gosub, app_gosubif, app_pop, app_return, ast_register_application(), gosub_descrip, gosub_exec(), gosub_synopsis, gosubif_descrip, gosubif_exec(), gosubif_synopsis, pop_descrip, pop_exec(), pop_synopsis, return_descrip, return_exec(), and return_synopsis.

    00167 {
    00168    ast_register_application(app_pop, pop_exec, pop_synopsis, pop_descrip);
    00169    ast_register_application(app_return, return_exec, return_synopsis, return_descrip);
    00170    ast_register_application(app_gosubif, gosubif_exec, gosubif_synopsis, gosubif_descrip);
    00171    ast_register_application(app_gosub, gosub_exec, gosub_synopsis, gosub_descrip);
    00172
    00173    return 0;
    00174 }

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

Definition at line 72 of file app_stack.c.

References pbx_builtin_setvar_helper(), and STACKVAR.

Referenced by load_module().

    00073 {
    00074    pbx_builtin_setvar_helper(chan, STACKVAR, NULL);
    00075
    00076    return 0;
    00077 }

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

Definition at line 79 of file app_stack.c.

References ast_log(), ast_parseable_goto(), ast_strlen_zero(), LOG_ERROR, LOG_WARNING, pbx_builtin_getvar_helper(), pbx_builtin_setvar_helper(), and STACKVAR.

Referenced by load_module().

    00080 {
    00081    char *label = pbx_builtin_getvar_helper(chan, STACKVAR);
    00082
    00083    if (ast_strlen_zero(label)) {
    00084       ast_log(LOG_ERROR, "Return without Gosub: stack is empty\n");
    00085       return -1;
    00086    } else if (ast_parseable_goto(chan, label)) {
    00087       ast_log(LOG_WARNING, "No next statement after Gosub?\n");
    00088       return -1;
    00089    }
    00090
    00091    pbx_builtin_setvar_helper(chan, STACKVAR, NULL);
    00092    return 0;
    00093 }

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 154 of file app_stack.c.

References app_gosub, app_gosubif, app_pop, app_return, ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00155 {
    00156    ast_unregister_application(app_return);
    00157    ast_unregister_application(app_pop);
    00158    ast_unregister_application(app_gosubif);
    00159    ast_unregister_application(app_gosub);
    00160
    00161    STANDARD_HANGUP_LOCALUSERS;
    00162
    00163    return 0;
    00164 }

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 181 of file app_stack.c.

References STANDARD_USECOUNT.

    00182 {
    00183    int res;
    00184
    00185    STANDARD_USECOUNT(res);
    00186
    00187    return res;
    00188 }

## Variable Documentation

const char* app_gosub = "Gosub"`[static]`

Definition at line 43 of file app_stack.c.

Referenced by gosub_exec(), load_module(), and unload_module().

const char* app_gosubif = "GosubIf"`[static]`

Definition at line 44 of file app_stack.c.

Referenced by load_module(), and unload_module().

const char* app_pop = "StackPop"`[static]`

Definition at line 46 of file app_stack.c.

Referenced by load_module(), and unload_module().

const char* app_return = "Return"`[static]`

Definition at line 45 of file app_stack.c.

Referenced by load_module(), and unload_module().

const char* gosub_descrip`[static]`

Initial value:

    "Gosub([[context|]exten|]priority)\n"
    "  Jumps to the label specified, saving the return address.\n"

Definition at line 53 of file app_stack.c.

Referenced by load_module().

const char* gosub_synopsis = "Jump to label, saving return address"`[static]`

Definition at line 48 of file app_stack.c.

Referenced by load_module().

const char* gosubif_descrip`[static]`

Initial value:

    "GosubIf(condition?labeliftrue[:labeliffalse])\n"
    "  If the condition is true, then jump to labeliftrue.  If false, jumps to\n"
    "labeliffalse, if specified.  In either case, a jump saves the return point\n"
    "in the dialplan, to be returned to with a Return.\n"

Definition at line 56 of file app_stack.c.

Referenced by load_module().

const char* gosubif_synopsis = "Jump to label, saving return address"`[static]`

Definition at line 49 of file app_stack.c.

Referenced by load_module().

LOCAL_USER_DECL

Definition at line 70 of file app_stack.c.

const char* pop_descrip`[static]`

Initial value:

    "StackPop()\n"
    "  Removes last label on the stack, discarding it.\n"

Definition at line 64 of file app_stack.c.

Referenced by load_module().

const char* pop_synopsis = "Remove one address from gosub stack"`[static]`

Definition at line 51 of file app_stack.c.

Referenced by load_module().

const char* return_descrip`[static]`

Initial value:

    "Return()\n"
    "  Jumps to the last label on the stack, removing it.\n"

Definition at line 61 of file app_stack.c.

Referenced by load_module().

const char* return_synopsis = "Return from gosub routine"`[static]`

Definition at line 50 of file app_stack.c.

Referenced by load_module().

STANDARD_LOCAL_USER

Definition at line 68 of file app_stack.c.

const char* tdesc = "Stack Routines"`[static]`

Definition at line 41 of file app_stack.c.