Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:59 2009

## Asterisk developer's documentation

# app_controlplayback.c File Reference

Trivial application to control playback of a sound file. 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/utils.h"`
`#include "asterisk/options.h"`

Include dependency graph for app_controlplayback.c:

Go to the source code of this file.

## Functions

static int | controlplayback_exec (struct ast_channel *chan, void *data)
char * | description (void)
| Provides a description of the module.
static int | is_on_phonepad (char key)
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
int | unload_module (void)
| Cleanup all module structures, sockets, etc.
int | usecount (void)
| Provides a usecount.

## Variables

static const char * | app = "ControlPlayback"
static const char * | descrip
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static const char * | synopsis = "Play a file with fast forward and rewind"
static const char * | tdesc = "Control Playback Application"

## Detailed Description

Trivial application to control playback of a sound file.

Definition in file app_controlplayback.c.

## Function Documentation

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

Definition at line 77 of file app_controlplayback.c.

References ast_app_separate_args(), ast_control_streamfile(), ast_goto_if_exists(), ast_log(), ast_strdupa, ast_strlen_zero(), ast_channel::context, ast_channel::exten, is_on_phonepad(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_WARNING, option_priority_jumping, pbx_builtin_setvar_helper(), ast_channel::priority, and skipms.

Referenced by load_module().

    00078 {
    00079    int res = 0, priority_jump = 0;
    00080    int skipms = 0;
    00081    struct localuser *u;
    00082    char *tmp;
    00083    int argc;
    00084    char *argv[8];
    00085    enum arg_ids {
    00086       arg_file = 0,
    00087       arg_skip = 1,
    00088       arg_fwd = 2,
    00089       arg_rev = 3,
    00090       arg_stop = 4,
    00091       arg_pause = 5,
    00092       arg_restart = 6,
    00093       options = 7,
    00094    };
    00095
    00096    if (ast_strlen_zero(data)) {
    00097       ast_log(LOG_WARNING, "ControlPlayback requires an argument (filename)\n");
    00098       return -1;
    00099    }
    00100
    00101    LOCAL_USER_ADD(u);
    00102
    00103    tmp = ast_strdupa(data);
    00104    memset(argv, 0, sizeof(argv));
    00105
    00106    argc = ast_app_separate_args(tmp, '|', argv, sizeof(argv) / sizeof(argv[0]));
    00107
    00108    if (argc < 1) {
    00109       ast_log(LOG_WARNING, "ControlPlayback requires an argument (filename)\n");
    00110       LOCAL_USER_REMOVE(u);
    00111       return -1;
    00112    }
    00113
    00114    skipms = argv[arg_skip] ? atoi(argv[arg_skip]) : 3000;
    00115    if (!skipms)
    00116       skipms = 3000;
    00117
    00118    if (!argv[arg_fwd] || !is_on_phonepad(*argv[arg_fwd]))
    00119       argv[arg_fwd] = "#";
    00120    if (!argv[arg_rev] || !is_on_phonepad(*argv[arg_rev]))
    00121       argv[arg_rev] = "*";
    00122    if (argv[arg_stop] && !is_on_phonepad(*argv[arg_stop]))
    00123       argv[arg_stop] = NULL;
    00124    if (argv[arg_pause] && !is_on_phonepad(*argv[arg_pause]))
    00125       argv[arg_pause] = NULL;
    00126    if (argv[arg_restart] && !is_on_phonepad(*argv[arg_restart]))
    00127       argv[arg_restart] = NULL;
    00128
    00129    if (argv[options]) {
    00130       if (strchr(argv[options], 'j'))
    00131          priority_jump = 1;
    00132    }
    00133
    00134    res = ast_control_streamfile(chan, argv[arg_file], argv[arg_fwd], argv[arg_rev], argv[arg_stop], argv[arg_pause], argv[arg_restart], skipms);
    00135
    00136    /* If we stopped on one of our stop keys, return 0  */
    00137    if (argv[arg_stop] && strchr(argv[arg_stop], res)) {
    00138       res = 0;
    00139       pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "USERSTOPPED");
    00140    } else {
    00141       if (res < 0) {
    00142          if (priority_jump || option_priority_jumping) {
    00143             if (ast_goto_if_exists(chan, chan->context, chan->exten, chan->priority + 101)) {
    00144                ast_log(LOG_WARNING, "ControlPlayback tried to jump to priority n+101 as requested, but priority didn't exist\n");
    00145             }
    00146          }
    00147          res = 0;
    00148          pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "ERROR");
    00149       } else
    00150          pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "SUCCESS");
    00151    }
    00152
    00153    LOCAL_USER_REMOVE(u);
    00154
    00155    return res;
    00156 }

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 174 of file app_controlplayback.c.

    00175 {
    00176    return (char *) tdesc;
    00177 }

static int is_on_phonepad | ( | char | key | ) | `[static]`

Definition at line 72 of file app_controlplayback.c.

Referenced by controlplayback_exec().

    00073 {
    00074    return key == 35 || key == 42 || (key >= 48 && key <= 57);
    00075 }

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 187 of file app_controlplayback.c.

References ASTERISK_GPL_KEY.

    00188 {
    00189    return ASTERISK_GPL_KEY;
    00190 }

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 169 of file app_controlplayback.c.

References ast_register_application(), and controlplayback_exec().

    00170 {
    00171    return ast_register_application(app, controlplayback_exec, synopsis, descrip);
    00172 }

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 158 of file app_controlplayback.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00159 {
    00160    int res;
    00161
    00162    res = ast_unregister_application(app);
    00163
    00164    STANDARD_HANGUP_LOCALUSERS;
    00165
    00166    return res;
    00167 }

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 179 of file app_controlplayback.c.

References STANDARD_USECOUNT.

    00180 {
    00181    int res;
    00182
    00183    STANDARD_USECOUNT(res);
    00184    return res;
    00185 }

## Variable Documentation

const char* app = "ControlPlayback"`[static]`

Definition at line 46 of file app_controlplayback.c.

const char* descrip`[static]`

Definition at line 50 of file app_controlplayback.c.

LOCAL_USER_DECL

Definition at line 70 of file app_controlplayback.c.

STANDARD_LOCAL_USER

Definition at line 68 of file app_controlplayback.c.

const char* synopsis = "Play a file with fast forward and rewind"`[static]`

Definition at line 48 of file app_controlplayback.c.

const char* tdesc = "Control Playback Application"`[static]`

Definition at line 44 of file app_controlplayback.c.