Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:10 2009

## Asterisk developer's documentation

# app_playback.c File Reference

Trivial application to playback a sound file. More...

`#include <string.h>`
`#include <stdlib.h>`
`#include <stdio.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/module.h"`
`#include "asterisk/translate.h"`
`#include "asterisk/utils.h"`
`#include "asterisk/options.h"`
`#include "asterisk/app.h"`

Include dependency graph for app_playback.c:

Go to the source code of this file.

## 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 | playback_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 = "Playback"
static char * | descrip
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static char * | synopsis = "Play a file"
static char * | tdesc = "Sound File Playback Application"

## Detailed Description

Trivial application to playback a sound file.

Definition in file app_playback.c.

## Function Documentation

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 166 of file app_playback.c.

    00167 {
    00168    return tdesc;
    00169 }

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 178 of file app_playback.c.

References ASTERISK_GPL_KEY.

    00179 {
    00180    return ASTERISK_GPL_KEY;
    00181 }

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 161 of file app_playback.c.

References ast_register_application(), and playback_exec().

    00162 {
    00163    return ast_register_application(app, playback_exec, synopsis, descrip);
    00164 }

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

Definition at line 71 of file app_playback.c.

References ast_channel::_state, ast_answer(), AST_APP_ARG, AST_DECLARE_APP_ARGS, ast_goto_if_exists(), ast_log(), AST_STANDARD_APP_ARGS, AST_STATE_UP, ast_stopstream(), ast_strdupa, ast_streamfile(), ast_strlen_zero(), ast_waitstream(), ast_channel::context, ast_channel::exten, ast_channel::language, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, LOG_WARNING, ast_channel::name, option_priority_jumping, pbx_builtin_setvar_helper(), ast_channel::priority, and strcasestr().

Referenced by load_module().

    00072 {
    00073    int res = 0, mres = 0;
    00074    struct localuser *u;
    00075    char *tmp = NULL;
    00076    int option_skip=0;
    00077    int option_noanswer = 0;
    00078    char *front = NULL, *back = NULL;
    00079    int priority_jump = 0;
    00080    AST_DECLARE_APP_ARGS(args,
    00081       AST_APP_ARG(filenames);
    00082       AST_APP_ARG(options);
    00083    );
    00084
    00085    if (ast_strlen_zero(data)) {
    00086       ast_log(LOG_WARNING, "Playback requires an argument (filename)\n");
    00087       return -1;
    00088    }
    00089
    00090    LOCAL_USER_ADD(u);
    00091
    00092    tmp = ast_strdupa(data);
    00093    if (!tmp) {
    00094       ast_log(LOG_ERROR, "Out of memory!\n");
    00095       LOCAL_USER_REMOVE(u);
    00096       return -1;
    00097    }
    00098
    00099    AST_STANDARD_APP_ARGS(args, tmp);
    00100
    00101    if (args.options) {
    00102       if (strcasestr(args.options, "skip"))
    00103          option_skip = 1;
    00104       if (strcasestr(args.options, "noanswer"))
    00105          option_noanswer = 1;
    00106       if (strchr(args.options, 'j'))
    00107          priority_jump = 1;
    00108    }
    00109
    00110    if (chan->_state != AST_STATE_UP) {
    00111       if (option_skip) {
    00112          /* At the user's option, skip if the line is not up */
    00113          pbx_builtin_setvar_helper(chan, "PLAYBACKSTATUS", "SUCCESS");
    00114          LOCAL_USER_REMOVE(u);
    00115          return 0;
    00116       } else if (!option_noanswer)
    00117          /* Otherwise answer unless we're supposed to send this while on-hook */
    00118          res = ast_answer(chan);
    00119    }
    00120    if (!res) {
    00121       ast_stopstream(chan);
    00122       front = tmp;
    00123       while (!res && front) {
    00124          if ((back = strchr(front, '&'))) {
    00125             *back = '\0';
    00126             back++;
    00127          }
    00128          res = ast_streamfile(chan, front, chan->language);
    00129          if (!res) {
    00130             res = ast_waitstream(chan, "");
    00131             ast_stopstream(chan);
    00132          } else {
    00133             ast_log(LOG_WARNING, "ast_streamfile failed on %s for %s\n", chan->name, (char *)data);
    00134             if (priority_jump || option_priority_jumping)
    00135                ast_goto_if_exists(chan, chan->context, chan->exten, chan->priority + 101);
    00136             res = 0;
    00137             mres = 1;
    00138          }
    00139          front = back;
    00140       }
    00141    }
    00142    if (mres)
    00143       pbx_builtin_setvar_helper(chan, "PLAYBACKSTATUS", "FAILED");
    00144    else
    00145       pbx_builtin_setvar_helper(chan, "PLAYBACKSTATUS", "SUCCESS");
    00146    LOCAL_USER_REMOVE(u);
    00147    return res;
    00148 }

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 150 of file app_playback.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00151 {
    00152    int res;
    00153
    00154    res = ast_unregister_application(app);
    00155
    00156    STANDARD_HANGUP_LOCALUSERS;
    00157
    00158    return res;
    00159 }

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 171 of file app_playback.c.

References STANDARD_USECOUNT.

    00172 {
    00173    int res;
    00174    STANDARD_USECOUNT(res);
    00175    return res;
    00176 }

## Variable Documentation

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

Definition at line 47 of file app_playback.c.

char* descrip`[static]`

Definition at line 51 of file app_playback.c.

LOCAL_USER_DECL

Definition at line 69 of file app_playback.c.

STANDARD_LOCAL_USER

Definition at line 67 of file app_playback.c.

char* synopsis = "Play a file"`[static]`

Definition at line 49 of file app_playback.c.

char* tdesc = "Sound File Playback Application"`[static]`

Definition at line 45 of file app_playback.c.